.\" Man page generated from reStructuredText.
.
.TH "CH-FROMHOST" "1" "2020-12-20 14:44 Coordinated Universal Time" "0.21" "Charliecloud"
.SH NAME
ch-fromhost \- Inject files from the host into an image directory, with various magic
.
.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\-fromhost [OPTION ...] [FILE_OPTION ...] IMGDIR
.ft P
.fi
.UNINDENT
.UNINDENT
.SH DESCRIPTION
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
This command is experimental. Features may be incomplete and/or buggy.
Please report any issues you find, so we can fix them!
.UNINDENT
.UNINDENT
.sp
Inject files from the host into the Charliecloud image directory
\fBIMGDIR\fP\&.
.sp
The purpose of this command is to inject files into a container image that are
necessary to run the container on a specific host; e.g., GPU libraries that
are tied to a specific kernel version. \fBIt is not a general copy\-to\-image
tool\fP; see further discussion on use cases below. It should be run after
\fBch\-tar2dir\fP and before \fBch\-run\fP\&. After invocation, the image is
no longer portable to other hosts.
.sp
Injection is not atomic; if an error occurs partway through injection, the
image is left in an undefined state. Injection is currently implemented using
a simple file copy, but that may change in the future.
.sp
By default, file paths that contain the strings \fB/bin\fP or \fB/sbin\fP
are assumed to be executables and placed in \fB/usr/bin\fP within the
container. File paths that contain the strings \fB/lib\fP or \fB\&.so\fP are
assumed to be shared libraries and are placed in the first\-priority directory
reported by \fBldconfig\fP (see \fB\-\-lib\-path\fP below). Other files are
placed in the directory specified by \fB\-\-dest\fP\&.
.sp
If any shared libraries are injected, run \fBldconfig\fP inside the
container (using \fBch\-run \-w\fP) after injection.
.SH OPTIONS
.SS To specify which files to inject
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.TP
.B \fB\-c\fP, \fB\-\-cmd CMD\fP
Inject files listed in the standard output of command \fBCMD\fP\&.
.TP
.B \fB\-f\fP, \fB\-\-file FILE\fP
Inject files listed in the file \fBFILE\fP\&.
.TP
.B \fB\-p\fP, \fB\-\-path PATH\fP
Inject the file at \fBPATH\fP\&.
.TP
.B \fB\-\-cray\-mpi\fP
Cray\-enable MPICH/OpenMPI installed inside the image. See important details
below.
.TP
.B \fB\-\-nvidia\fP
Use \fBnvidia\-container\-cli list\fP (from \fBlibnvidia\-container\fP)
to find executables and libraries to inject.
.UNINDENT
.UNINDENT
.UNINDENT
.sp
These can be repeated, and at least one must be specified.
.SS To specify the destination within the image
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.TP
.B \fB\-d\fP, \fB\-\-dest DST\fP
Place files specified later in directory \fBIMGDIR/DST\fP, overriding the
inferred destination, if any. If a file’s destination cannot be inferred
and \fB\-\-dest\fP has not been specified, exit with an error. This can be
repeated to place files in varying destinations.
.UNINDENT
.UNINDENT
.UNINDENT
.SS Additional arguments
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.TP
.B \fB\-\-lib\-path\fP
Print the guest destination path for shared libraries inferred as
described above.
.TP
.B \fB\-\-no\-ldconfig\fP
Don’t run \fBldconfig\fP even if we appear to have injected shared
libraries.
.TP
.B \fB\-h\fP, \fB\-\-help\fP
Print help and exit.
.TP
.B \fB\-v\fP, \fB\-\-verbose\fP
List the injected files.
.TP
.B \fB\-\-version\fP
Print version and exit.
.UNINDENT
.UNINDENT
.UNINDENT
.SH WHEN TO USE CH-FROMHOST
.sp
This command does a lot of heuristic magic; while it \fIcan\fP copy arbitrary
files into an image, this usage is discouraged and prone to error. Here are
some use cases and the recommended approach:
.INDENT 0.0
.IP 1. 3
\fII have some files on my build host that I want to include in the image.\fP
Use the \fBCOPY\fP instruction within your Dockerfile. Note that it’s OK
to build an image that meets your specific needs but isn’t generally
portable, e.g., only runs on specific micro\-architectures you’re using.
.IP 2. 3
\fII have an already built image and want to install a program I compiled
separately into the image.\fP Consider whether a building a new derived image
with a Dockerfile is appropriate. Another good option is to bind\-mount the
directory containing your program at run time. A less good option is to
\fBcp(1)\fP the program into your image, because this permanently alters
the image in a non\-reproducible way.
.IP 3. 3
\fII have some shared libraries that I need in the image for functionality or
performance, and they aren’t available in a place where I can use\fP
\fBCOPY\fP\&. This is the intended use case of \fBch\-fromhost\fP\&. You can
use \fB\-\-cmd\fP, \fB\-\-file\fP, and/or \fB\-\-path\fP to put together a
custom solution. But, please consider filing an issue so we can package
your functionality with a tidy option like \fB\-\-cray\-mpi\fP or
\fB\-\-nvidia\fP\&.
.UNINDENT
.SH --CRAY-MPI DEPENDENCIES AND QUIRKS
.sp
The implementation of \fB\-\-cray\-mpi\fP is messy, foul smelling, and brittle.
It replaces or overrides the MPICH or OpenMPI libraries installed in the
container. Users should be aware of the following.
.INDENT 0.0
.IP 1. 3
Containers must have the following software installed:
.INDENT 3.0
.IP a. 3
Corresponding open source MPI implementation. (\fI\%MPICH\fP and \fI\%OpenMPI\fP\&.)
.IP b. 3
\fI\%PatchELF with our patches\fP\&.
Use the \fBshrink\-soname\fP branch. (MPICH only.)
.IP c. 3
\fBlibgfortran.so.3\fP, because Cray’s \fBlibmpi.so.12\fP
links to it. (MPICH only.)
.UNINDENT
.IP 2. 3
Applications must be dynamically linked to \fBlibmpi.so.12\fP (not e.g.
\fBlibmpich.so.12\fP).
.INDENT 3.0
.IP a. 3
How to configure MPICH to accomplish this is not yet clear to us;
\fBtest/Dockerfile.mpich\fP does it, while the Debian packages do not.
(MPICH only.)
.UNINDENT
.IP 3. 3
An ABI compatible module for the given MPI implementation must be loaded
when \fBch\-fromhost\fP is invoked.
.INDENT 3.0
.IP a. 3
Load the \fBcray\-mpich\-abi\fP module. (MPICH only.)
.IP b. 3
We recommend loading the module of a version as close to what
is installed in the image as possible. This OpenMPI install needs to be
built such that libmpi contains all needed plugins (as opposed to them
being standalone shared libraries). See \fI\%OpenMPI’s documentation\fP for how to do this.
(OpenMPI only.)
.UNINDENT
.IP 4. 3
Tested only for C programs compiled with GCC, and it probably won’t work
otherwise. If you’d like to use another compiler or another programming
language, please get in touch so we can implement the necessary support.
.UNINDENT
.sp
Please file a bug if we missed anything above or if you know how to make the
code better.
.SH NOTES
.sp
Symbolic links are dereferenced, i.e., the files pointed to are injected, not
the links themselves.
.sp
As a corollary, do not include symlinks to shared libraries. These will be
re\-created by \fBldconfig\fP\&.
.sp
There are two alternate approaches for nVidia GPU libraries:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP 1. 3
Link \fBlibnvidia\-containers\fP into \fBch\-run\fP and call the
library functions directly. However, this would mean that Charliecloud
would either (a) need to be compiled differently on machines with and
without nVidia GPUs or (b) have \fBlibnvidia\-containers\fP available
even on machines without nVidia GPUs. Neither of these is consistent with
Charliecloud’s philosophies of simplicity and minimal dependencies.
.IP 2. 3
Use \fBnvidia\-container\-cli configure\fP to do the injecting. This
would require that containers have a half\-started state, where the
namespaces are active and everything is mounted but \fBpivot_root(2)\fP
has not been performed. This is not feasible because Charliecloud has no
notion of a half\-started container.
.UNINDENT
.UNINDENT
.UNINDENT
.sp
Further, while these alternate approaches would simplify or eliminate this
script for nVidia GPUs, they would not solve the problem for other situations.
.SH BUGS
.sp
File paths may not contain colons or newlines.
.SH EXAMPLES
.sp
Place shared library \fB/usr/lib64/libfoo.so\fP at path
\fB/usr/lib/libfoo.so\fP (assuming \fB/usr/lib\fP is the first directory
searched by the dynamic loader in the image), within the image
\fB/var/tmp/baz\fP and executable \fB/bin/bar\fP at path
\fB/usr/bin/bar\fP\&. Then, create appropriate symlinks to \fBlibfoo\fP and
update the \fBld.so\fP cache.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ cat qux.txt
/bin/bar
/usr/lib64/libfoo.so
$ ch\-fromhost \-\-file qux.txt /var/tmp/baz
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Same as above:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ ch\-fromhost \-\-cmd \(aqcat qux.txt\(aq /var/tmp/baz
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Same as above:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ ch\-fromhost \-\-path /bin/bar \-\-path /usr/lib64/libfoo.so /var/tmp/baz
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Same as above, but place the files into \fB/corge\fP instead (and the shared
library will not be found by \fBldconfig\fP):
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ ch\-fromhost \-\-dest /corge \-\-file qux.txt /var/tmp/baz
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Same as above, and also place file \fB/etc/quux\fP at \fB/etc/quux\fP
within the container:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ ch\-fromhost \-\-file qux.txt \-\-dest /etc \-\-path /etc/quux /var/tmp/baz
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Inject the executables and libraries recommended by nVidia into the image, and
then run \fBldconfig\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ ch\-fromhost \-\-nvidia /var/tmp/baz
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Inject the Cray\-enabled MPI libraries into the image, and then run
\fBldconfig\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ ch\-fromhost \-\-cray\-mpi /var/tmp/baz
.ft P
.fi
.UNINDENT
.UNINDENT
.SH ACKNOWLEDGEMENTS
.sp
This command was inspired by the similar \fI\%Shifter\fP feature
that allows Shifter containers to use the Cray Aries network. We particularly
appreciate the help provided by Shane Canon and Doug Jacobsen during our
implementation of \fB\-\-cray\-mpi\fP\&.
.sp
We appreciate the advice of Ryan Olson at nVidia on implementing
\fB\-\-nvidia\fP\&.
.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(7)
.sp
Full documentation at: <\fI\%https://hpc.github.io/charliecloud\fP>
.SH COPYRIGHT
2014–2020, Triad National Security, LLC
.\" Generated by docutils manpage writer.
.