discuss limitations which apply to dumping images with IMAGE-DUMPED

Signed-off-by: Sean Whitton <spwhitton@spwhitton.name>

2 files changed, 51 insertions, 3 deletions

diff --git a/doc/pitfalls.rst b/doc/pitfalls.rst
index b0610eb..7c3b7d3 100644
--- a/doc/pitfalls.rst
+++ b/doc/pitfalls.rst
@@ -1,5 +1,5 @@
-Pitfalls
-========
+Pitfalls and limitations
+========================
 
 Invoking properties from within properties
 ------------------------------------------
@@ -79,3 +79,50 @@ atomic property applications will look like invalid function calls to the code
 walker.  Avoiding this would seem to require wrapping the propspec in one
 macrolet for each known property, and this makes ``MACROEXPAND-ALL`` too slow,
 even if the macrolet forms are precomputed.
+
+Dumping and reinvoking Lisp
+---------------------------
+
+Remote Lisp images can dump executable images of themselves using the
+IMAGE-DUMPED property.  However, there are some limitations to how this
+feature can be used that are connected with changing execution context in the
+way that connection types like :CHROOT.FORK and :SETUID do.
+
+Firstly, for at least some Lisp implementations, the build of Lisp that's
+running must be accessible via the filesystem in order for it to be possible
+to dump an image.  In the case of SBCL, for example, the very same
+/usr/bin/sbcl and /usr/lib/sbcl/sbcl.core need to be accessible.  If
+Consfigurator has forked into a chroot then this may not be the case.  So, for
+example, when preparing a disk image by applying properties to a chroot, you
+can't easily apply a property like CRON:RUNS-CONSFIGURATOR.  See the docstring
+for IMAGE-DUMPED for one way to handle this situation.
+
+Secondly, dumped images can fail to start up at all if they cannot reopen all
+the shared libraries they had open right before the dump, and if the execution
+context has changed, these files might not be readable anymore.  For example,
+if Consfigurator has forked into a chroot and then dumped an image, libacl1.so
+might not be present at all, or -- what is more likely in the case of that
+particular library -- only accessible via a different path.  Additionally, the
+use of the CFFI groveller by Consfigurator and its dependency Osicat means
+that the reinvoked image will try to load shared libraries out of the
+~/.cache/common-lisp belonging to the user who originally started up the
+remote Lisp image.  For example, if :SETUID has been used to switch from root
+to an unprivileged user, and then an image is dumped, the unprivileged user
+won't be able to execute that image.  This is because the unprivileged user
+cannot typically read files under /root/.cache/common-lisp.
+
+This second issue could be partly mitigated using CFFI's ``STATIC-PROGRAM-OP``
+ASDF operation, as described in the "Static Linking" section of the CFFI
+manual.  This is not currently implemented, for several reasons.  Firstly, it
+is less portable than the current CFFI features we use, and does not actually
+solve the problem of inaccessible system libraries like libacl1.so, only the
+problem of files under ~/.cache/common-lisp.  Secondly, there are unsolved
+difficulties integrating it with some of Consfigurator's standard usage
+patterns, such as calls to TRY-REGISTER-DATA-SOURCE which appear directly in
+consfigs (STATIC-PROGRAM-OP tries to load up consfigs in another Lisp image
+without a way for us to bind *NO-DATA-SOURCES*).  Thirdly, [CFFI currently
+tries to reopen all shared libraries upon reinvocation regardless of the use
+of STATIC-PROGRAM-OP](https://github.com/cffi/cffi/pull/163).  Finally, many
+builds of SBCL (including Debian's at the time of writing) can't get all the
+way through STATIC-PROGRAM-OP without hacks like manually setting the
+SBCL_HOME environment variable before starting the attempt.
diff --git a/src/image.lisp b/src/image.lisp
index 28e1df1..0f136d5 100644
--- a/src/image.lisp
+++ b/src/image.lisp
@@ -287,7 +287,8 @@ then quietly skip over this property by applying it like this:
 ;; a remote Lisp image and every time we establish a further FORK-CONNECTION,
 ;; however, though perhaps we could arrange to avoid dumping an executable if
 ;; we know that we aren't going to need to reinvoke it, by having connection
-;; types push hostattrs.
+;; types push hostattrs.  We would also need to resolve issues detailed under
+;; "Dumping and reinvoking Lisp" in pitfalls.rst.
 ;;
 ;; If we took this approach, then we'd have implementation-specific dumping
 ;; code, but the code to reinvoke the dumped images would be fully portable --