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

NAME

6       ch-fromhost - Inject files from the host into an image directory
7

SYNOPSIS

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

DESCRIPTION

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
16       Inject files from  the  host  into  the  Charliecloud  image  directory
17       IMGDIR.
18
19       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
24       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
28       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
35       If any shared libraries are injected, run ldconfig inside the container
36       (using ch-run -w) after injection.
37

OPTIONS

39   To specify which files to inject
40          -c, --cmd CMD
41                 Inject files listed in the standard output of command CMD.
42
43          -f, --file FILE
44                 Inject files listed in the file FILE.
45
46          -p, --path PATH
47                 Inject the file at PATH.
48
49          --cray-mpi
50                 Cray-enable an MPICH installed inside the image.  See  impor‐
51                 tant details below.
52
53          --nvidia
54                 Use  nvidia-container-cli  list (from libnvidia-container) to
55                 find executables and libraries to inject.
56
57       These can be repeated, and at least one must be specified.
58
59   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
67   Additional arguments
68          --lib-path
69                 Print  the  guest  destination  path  for  shared   libraries
70                 inferred as described above.
71
72          --no-ldconfig
73                 Don’t  run ldconfig even if we appear to have injected shared
74                 libraries.
75
76          -h, --help
77                 Print help and exit.
78
79          -v, --verbose
80                 List the injected files.
81
82          --version
83                 Print version and exit.
84

--CRAY-MPI DEPENDENCIES AND QUIRKS

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
90       1. Containers must have the following software installed:
91
92          a. Open source MPICH.
93
94          b. PatchELF with our patches. Use the shrink-soname branch.
95
96          c. libgfortran.so.3, because Cray’s libmpi.so.12 links to it.
97
98       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
103       3. One of the cray-mpich-abi modules must be loaded when ch-fromhost is
104          invoked.
105
106       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
111       Please  file  a  bug  if we missed anything above or if you know how to
112       make the code better.
113

NOTES

115       Symbolic links  are  dereferenced,  i.e.,  the  files  pointed  to  are
116       injected, not the links themselves.
117
118       As a corollary, do not include symlinks to shared libraries. These will
119       be re-created by ldconfig.
120
121       There are two alternate approaches for nVidia GPU libraries:
122
123          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
131          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
137       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

BUGS

142       File paths may not contain colons or newlines.
143

EXAMPLES

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
151          $ cat qux.txt
152          /bin/bar
153          /usr/lib64/libfoo.so
154          $ ch-fromhost --file qux.txt /var/tmp/baz
155
156       Same as above:
157
158          $ ch-fromhost --cmd 'cat qux.txt' /var/tmp/baz
159
160       Same as above:
161
162          $ ch-fromhost --path /bin/bar --path /usr/lib64/libfoo.so /var/tmp/baz
163
164       Same as above, but place the files into /corge instead (and the  shared
165       library will not be found by ldconfig):
166
167          $ ch-fromhost --dest /corge --file qux.txt /var/tmp/baz
168
169       Same  as  above,  and also place file /etc/quux at /etc/quux within the
170       container:
171
172          $ ch-fromhost --file qux.txt --dest /etc --path /etc/quux /var/tmp/baz
173
174       Inject the executables and libraries recommended  by  nVidia  into  the
175       image, and then run ldconfig:
176
177          $ ch-fromhost --nvidia /var/tmp/baz
178

ACKNOWLEDGEMENTS

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
185       We appreciate the advice  of  Ryan  Olson  at  nVidia  on  implementing
186       --nvidia.
187

REPORTING BUGS

189       If  Charliecloud  was  obtained  from your Linux distribution, use your
190       distribution’s bug reporting procedures.
191
192       Otherwise, report bugs to: <https://github.com/hpc/charliecloud/issues>
193

SEE ALSO

195       charliecloud(1)
196
197       Full documentation at: <https://hpc.github.io/charliecloud>
198

AUTHOR

200       Reid Priedhorsky, Tim Randles, and others
201
203       2014–2018, Los Alamos National Security, LLC
204
205
206
207
208                  2019-08-22 00:00 Coordinated Universal Time   CH-FROMHOST(1)
Impressum