1CH-FROMHOST(1) Charliecloud CH-FROMHOST(1)
2
6 ch-fromhost - Inject files from the host into an image directory
7
9 $ ch-fromhost [OPTION ...] [FILE_OPTION ...] IMGDIR
10
12 NOTE:
13 This command is experimental. Features may be incomplete and/or
14 buggy. Please report any issues you find, so we can fix them!
15 Inject files from the host into the Charliecloud image directory
17 IMGDIR.
18 The purpose of this command is to provide host-specific files, such as
20 GPU libraries, to a container. It should be run after ch-tar2dir and
21 before ch-run. After invocation, the image is no longer portable to
22 other hosts.
23 Injection is not atomic; if an error occurs partway through injection,
25 the image is left in an undefined state. Injection is currently imple‐
26 mented using a simple file copy, but that may change in the future.
27 By default, file paths that contain the strings /bin or /sbin are
29 assumed to be executables and placed in /usr/bin within the container.
30 File paths that contain the strings /lib or .so are assumed to be
31 shared libraries and are placed in the first-priority directory
32 reported by ldconfig (see --lib-path below). Other files are placed in
33 the directory specified by --dest.
34 If any shared libraries are injected, run ldconfig inside the container
36 (using ch-run -w) after injection.
37
39 To specify which files to inject
40 -c, --cmd CMD
41 Inject files listed in the standard output of command CMD.
42 -f, --file FILE
44 Inject files listed in the file FILE.
45 -p, --path PATH
47 Inject the file at PATH.
48 --cray-mpi
50 Cray-enable an MPICH installed inside the image. See impor‐
51 tant details below.
52 --nvidia
54 Use nvidia-container-cli list (from libnvidia-container) to
55 find executables and libraries to inject.
56 These can be repeated, and at least one must be specified.
58 To specify the destination within the image
60 -d, --dest DST
61 Place files specified later in directory IMGDIR/DST, overrid‐
62 ing the inferred destination, if any. If a file’s destination
63 cannot be inferred and --dest has not been specified, exit
64 with an error. This can be repeated to place files in varying
65 destinations.
66 Additional arguments
68 --lib-path
69 Print the guest destination path for shared libraries
70 inferred as described above.
71 --no-ldconfig
73 Don’t run ldconfig even if we appear to have injected shared
74 libraries.
75 -h, --help
77 Print help and exit.
78 -v, --verbose
80 List the injected files.
81 --version
83 Print version and exit.
84
86 The implementation of --cray-mpi for MPICH is messy, foul smelling, and
87 brittle. It replaces or overrides the open source MPICH libraries
88 installed in the container. Users should be aware of the following.
89 1. Containers must have the following software installed:
91 a. Open source MPICH.
93 b. PatchELF with our patches. Use the shrink-soname branch.
95 c. libgfortran.so.3, because Cray’s libmpi.so.12 links to it.
97 2. Applications must be linked to libmpi.so.12 (not e.g.
99 libmpich.so.12). How to configure MPICH to accomplish this is not
100 yet clear to us; test/Dockerfile.mpich does it, while the Debian
101 packages do not.
102 3. One of the cray-mpich-abi modules must be loaded when ch-fromhost is
104 invoked.
105 4. Tested only for C programs compiled with GCC, and it probably won’t
107 work otherwise. If you’d like to use another compiler or another
108 programming language, please get in touch so we can implement the
109 necessary support.
110 Please file a bug if we missed anything above or if you know how to
112 make the code better.
113
115 Symbolic links are dereferenced, i.e., the files pointed to are
116 injected, not the links themselves.
117 As a corollary, do not include symlinks to shared libraries. These will
119 be re-created by ldconfig.
120 There are two alternate approaches for nVidia GPU libraries:
122 1. Link libnvidia-containers into ch-run and call the library func‐
124 tions directly. However, this would mean that Charliecloud would
125 either (a) need to be compiled differently on machines with and
126 without nVidia GPUs or (b) have libnvidia-containers available
127 even on machines without nVidia GPUs. Neither of these is consis‐
128 tent with Charliecloud’s philosophies of simplicity and minimal
129 dependencies.
130 2. Use nvidia-container-cli configure to do the injecting. This
132 would require that containers have a half-started state, where
133 the namespaces are active and everything is mounted but
134 pivot_root(2) has not been performed. This is not feasible
135 because Charliecloud has no notion of a half-started container.
136 Further, while these alternate approaches would simplify or eliminate
138 this script for nVidia GPUs, they would not solve the problem for other
139 situations.
140
142 File paths may not contain colons or newlines.
143
145 Place shared library /usr/lib64/libfoo.so at path /usr/lib/libfoo.so
146 (assuming /usr/lib is the first directory searched by the dynamic
147 loader in the image), within the image /var/tmp/baz and executable
148 /bin/bar at path /usr/bin/bar. Then, create appropriate symlinks to
149 libfoo and update the ld.so cache.
150 $ cat qux.txt
152 /bin/bar
153 /usr/lib64/libfoo.so
154 $ ch-fromhost --file qux.txt /var/tmp/baz
155 Same as above:
157 $ ch-fromhost --cmd 'cat qux.txt' /var/tmp/baz
159 Same as above:
161 $ ch-fromhost --path /bin/bar --path /usr/lib64/libfoo.so /var/tmp/baz
163 Same as above, but place the files into /corge instead (and the shared
165 library will not be found by ldconfig):
166 $ ch-fromhost --dest /corge --file qux.txt /var/tmp/baz
168 Same as above, and also place file /etc/quux at /etc/quux within the
170 container:
171 $ ch-fromhost --file qux.txt --dest /etc --path /etc/quux /var/tmp/baz
173 Inject the executables and libraries recommended by nVidia into the
175 image, and then run ldconfig:
176 $ ch-fromhost --nvidia /var/tmp/baz
178
180 This command was inspired by the similar Shifter feature that allows
181 Shifter containers to use the Cray Aires network. We particularly
182 appreciate the help provided by Shane Canon and Doug Jacobsen during
183 our implementation of --cray-mpi.
184 We appreciate the advice of Ryan Olson at nVidia on implementing
186 --nvidia.
187
189 If Charliecloud was obtained from your Linux distribution, use your
190 distribution’s bug reporting procedures.
191 Otherwise, report bugs to: <https://github.com/hpc/charliecloud/issues>
193
195 charliecloud(1)
196 Full documentation at: <https://hpc.github.io/charliecloud>
198
200 Reid Priedhorsky, Tim Randles, and others
201
203 2014–2018, Los Alamos National Security, LLC
204 2019-08-22 00:00 Coordinated Universal Time CH-FROMHOST(1)