1CH-FROMHOST(1)                   Charliecloud                   CH-FROMHOST(1)
2
3
4

NAME

6       ch-fromhost  - Inject files from the host into an image directory, with
7       various magic
8

SYNOPSIS

10          $ ch-fromhost [OPTION ...] [FILE_OPTION ...] IMGDIR
11

DESCRIPTION

13       NOTE:
14          This command is experimental.  Features  may  be  incomplete  and/or
15          buggy.  Please report any issues you find, so we can fix them!
16
17       Inject  files  from  the  host  into  the  Charliecloud image directory
18       IMGDIR.
19
20       The purpose of this command is to inject files into a  container  image
21       that  are  necessary to run the container on a specific host; e.g., GPU
22       libraries that are tied to a specific kernel version. It is not a  gen‐
23       eral  copy-to-image tool; see further discussion on use cases below. It
24       should be run after ch-tar2dir and before ch-run. After invocation, the
25       image is no longer portable to other hosts.
26
27       Injection  is not atomic; if an error occurs partway through injection,
28       the image is left in an undefined state. Injection is currently  imple‐
29       mented using a simple file copy, but that may change in the future.
30
31       By  default,  file  paths  that  contain  the strings /bin or /sbin are
32       assumed to be executables and placed in /usr/bin within the  container.
33       File  paths  that  contain  the  strings  /lib or .so are assumed to be
34       shared  libraries  and  are  placed  in  the  first-priority  directory
35       reported  by ldconfig (see --lib-path below). Other files are placed in
36       the directory specified by --dest.
37
38       If any shared libraries are injected, run ldconfig inside the container
39       (using ch-run -w) after injection.
40

OPTIONS

42   To specify which files to inject
43          -c, --cmd CMD
44                 Inject files listed in the standard output of command CMD.
45
46          -f, --file FILE
47                 Inject files listed in the file FILE.
48
49          -p, --path PATH
50                 Inject the file at PATH.
51
52          --cray-mpi
53                 Cray-enable  MPICH/OpenMPI  installed  inside  the image. See
54                 important details below.
55
56          --nvidia
57                 Use nvidia-container-cli list (from  libnvidia-container)  to
58                 find executables and libraries to inject.
59
60       These can be repeated, and at least one must be specified.
61
62   To specify the destination within the image
63          -d, --dest DST
64                 Place files specified later in directory IMGDIR/DST, overrid‐
65                 ing the inferred destination, if any. If a file’s destination
66                 cannot  be  inferred  and --dest has not been specified, exit
67                 with an error. This can be repeated to place files in varying
68                 destinations.
69
70   Additional arguments
71          --lib-path
72                 Print   the  guest  destination  path  for  shared  libraries
73                 inferred as described above.
74
75          --no-ldconfig
76                 Don’t run ldconfig even if we appear to have injected  shared
77                 libraries.
78
79          -h, --help
80                 Print help and exit.
81
82          -v, --verbose
83                 List the injected files.
84
85          --version
86                 Print version and exit.
87

WHEN TO USE CH-FROMHOST

89       This command does a lot of heuristic magic; while it can copy arbitrary
90       files into an image, this usage is discouraged and prone to error. Here
91       are some use cases and the recommended approach:
92
93       1. I  have  some  files  on my build host that I want to include in the
94          image.  Use the COPY instruction within your Dockerfile.  Note  that
95          it’s  OK  to build an image that meets your specific needs but isn’t
96          generally portable, e.g., only runs on specific  micro-architectures
97          you’re using.
98
99       2. I  have  an already built image and want to install a program I com‐
100          piled separately into the image. Consider whether a building  a  new
101          derived  image with a Dockerfile is appropriate. Another good option
102          is to bind-mount the directory containing your program at run  time.
103          A  less good option is to cp(1) the program into your image, because
104          this permanently alters the image in a non-reproducible way.
105
106       3. I have some shared libraries that I need in the image for  function‐
107          ality  or  performance, and they aren’t available in a place where I
108          can use COPY. This is the intended use case of ch-fromhost. You  can
109          use  --cmd, --file, and/or --path to put together a custom solution.
110          But, please consider filing an issue so we can  package  your  func‐
111          tionality with a tidy option like --cray-mpi or --nvidia.
112

--CRAY-MPI DEPENDENCIES AND QUIRKS

114       The  implementation of --cray-mpi is messy, foul smelling, and brittle.
115       It replaces or overrides the MPICH or OpenMPI  libraries  installed  in
116       the container. Users should be aware of the following.
117
118       1. Containers must have the following software installed:
119
120          a. Corresponding   open   source   MPI  implementation.  (MPICH  and
121             OpenMPI.)
122
123          b. PatchELF with our patches.  Use the shrink-soname branch.  (MPICH
124             only.)
125
126          c. libgfortran.so.3, because Cray’s libmpi.so.12 links to it. (MPICH
127             only.)
128
129       2. Applications must be dynamically linked to  libmpi.so.12  (not  e.g.
130          libmpich.so.12).
131
132          a. How to configure MPICH to accomplish this is not yet clear to us;
133             test/Dockerfile.mpich does it, while the Debian packages do  not.
134             (MPICH only.)
135
136       3. An  ABI  compatible  module for the given MPI implementation must be
137          loaded when ch-fromhost is invoked.
138
139          a. Load the cray-mpich-abi module. (MPICH only.)
140
141          b. We recommend loading the module of a version as close to what  is
142             installed in the image as possible. This OpenMPI install needs to
143             be built such that libmpi contains all needed plugins (as opposed
144             to  them  being standalone shared libraries). See OpenMPI’s docu‐
145             mentation for how to do this.  (OpenMPI only.)
146
147       4. Tested only for C programs compiled with GCC, and it probably  won’t
148          work  otherwise.  If  you’d  like to use another compiler or another
149          programming language, please get in touch so we  can  implement  the
150          necessary support.
151
152       Please  file  a  bug  if we missed anything above or if you know how to
153       make the code better.
154

NOTES

156       Symbolic links  are  dereferenced,  i.e.,  the  files  pointed  to  are
157       injected, not the links themselves.
158
159       As a corollary, do not include symlinks to shared libraries. These will
160       be re-created by ldconfig.
161
162       There are two alternate approaches for nVidia GPU libraries:
163
164          1. Link libnvidia-containers into ch-run and call the library  func‐
165             tions  directly. However, this would mean that Charliecloud would
166             either (a) need to be compiled differently on machines  with  and
167             without  nVidia  GPUs  or (b) have libnvidia-containers available
168             even on machines without nVidia GPUs. Neither of these is consis‐
169             tent  with  Charliecloud’s philosophies of simplicity and minimal
170             dependencies.
171
172          2. Use nvidia-container-cli configure  to  do  the  injecting.  This
173             would  require  that  containers have a half-started state, where
174             the  namespaces  are  active  and  everything  is   mounted   but
175             pivot_root(2)  has  not  been  performed.  This  is  not feasible
176             because Charliecloud has no notion of a half-started container.
177
178       Further, while these alternate approaches would simplify  or  eliminate
179       this script for nVidia GPUs, they would not solve the problem for other
180       situations.
181

BUGS

183       File paths may not contain colons or newlines.
184

EXAMPLES

186       Place shared library /usr/lib64/libfoo.so  at  path  /usr/lib/libfoo.so
187       (assuming  /usr/lib  is  the  first  directory  searched by the dynamic
188       loader in the image), within  the  image  /var/tmp/baz  and  executable
189       /bin/bar  at  path  /usr/bin/bar.  Then, create appropriate symlinks to
190       libfoo and update the ld.so cache.
191
192          $ cat qux.txt
193          /bin/bar
194          /usr/lib64/libfoo.so
195          $ ch-fromhost --file qux.txt /var/tmp/baz
196
197       Same as above:
198
199          $ ch-fromhost --cmd 'cat qux.txt' /var/tmp/baz
200
201       Same as above:
202
203          $ ch-fromhost --path /bin/bar --path /usr/lib64/libfoo.so /var/tmp/baz
204
205       Same as above, but place the files into /corge instead (and the  shared
206       library will not be found by ldconfig):
207
208          $ ch-fromhost --dest /corge --file qux.txt /var/tmp/baz
209
210       Same  as  above,  and also place file /etc/quux at /etc/quux within the
211       container:
212
213          $ ch-fromhost --file qux.txt --dest /etc --path /etc/quux /var/tmp/baz
214
215       Inject the executables and libraries recommended  by  nVidia  into  the
216       image, and then run ldconfig:
217
218          $ ch-fromhost --nvidia /var/tmp/baz
219
220       Inject  the  Cray-enabled  MPI  libraries  into the image, and then run
221       ldconfig:
222
223          $ ch-fromhost --cray-mpi /var/tmp/baz
224

ACKNOWLEDGEMENTS

226       This command was inspired by the similar Shifter  feature  that  allows
227       Shifter  containers  to  use  the  Cray  Aries network. We particularly
228       appreciate the help provided by Shane Canon and  Doug  Jacobsen  during
229       our implementation of --cray-mpi.
230
231       We  appreciate  the  advice  of  Ryan  Olson  at nVidia on implementing
232       --nvidia.
233

REPORTING BUGS

235       If Charliecloud was obtained from your  Linux  distribution,  use  your
236       distribution’s bug reporting procedures.
237
238       Otherwise, report bugs to: <https://github.com/hpc/charliecloud/issues>
239

SEE ALSO

241       charliecloud(7)
242
243       Full documentation at: <https://hpc.github.io/charliecloud>
244
246       2014–2020, Triad National Security, LLC
247
248
249
250
2510.22              2021-03-08 00:00 Coordinated Universal Time   CH-FROMHOST(1)
Impressum