discuss limitations which apply to dumping images with IMAGE-DUMPED

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

1 files changed, 49 insertions, 2 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.