scripts: Add 'container' subcommand.

* guix/scripts/container.scm: New file.
* guix/scripts/container/exec.scm: New file.
* po/guix/POTFILES.in: Add them.
* Makefile.am (MODULES): Add them.
* doc/guix.texi (Invoking guix container): New section.

1 files changed, 51 insertions, 0 deletions

diff --git a/doc/guix.texi b/doc/guix.texi
index 9e15cbd601..e107b698da 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -144,6 +144,7 @@ Utilities
 * Invoking guix environment::   Setting up development environments.
 * Invoking guix publish::       Sharing substitutes.
 * Invoking guix challenge::     Challenging substitute servers.
+* Invoking guix container::     Process isolation.
 
 GNU Distribution
 
@@ -3582,6 +3583,7 @@ programming interface of Guix in a convenient way.
 * Invoking guix environment::   Setting up development environments.
 * Invoking guix publish::       Sharing substitutes.
 * Invoking guix challenge::     Challenging substitute servers.
+* Invoking guix container::     Process isolation.
 @end menu
 
 @node Invoking guix build
@@ -4985,6 +4987,55 @@ URLs to compare to.
 @end table
 
 
+@node Invoking guix container
+@section Invoking @command{guix container}
+@cindex container
+
+The purpose of @command{guix container} is to manipulate processes
+running within an isolated environment, commonly known as a
+``container,'' typically created by the @command{guix environment}
+(@pxref{Invoking guix environment}) and @command{guix system container}
+(@pxref{Invoking guix system}) commands.
+
+The general syntax is:
+
+@example
+guix container @var{action} @var{options}@dots{}
+@end example
+
+@var{action} specifies the operation to perform with a container, and
+@var{options} specifies the context-specific arguments for the action.
+
+The following actions are available:
+
+@table @code
+@item exec
+Execute a command within the context of a running container.
+
+The syntax is:
+
+@example
+guix container exec @var{pid} @var{program} @var{arguments}@dots{}
+@end example
+
+@var{pid} specifies the process ID of the running container.
+@var{program} specifies an executable file name within the container's
+root file system.  @var{arguments} are the additional options that will
+be passed to @var{program}.
+
+The following command launches an interactive login shell inside a
+GuixSD container, started by @command{guix system container}, and whose
+process ID is 9001:
+
+@example
+guix container exec 9001 /run/current-system/profile/bin/bash --login
+@end example
+
+Note that the @var{pid} cannot be the parent process of a container.  It
+must be the container's PID 1 or one of its child processes.
+
+@end table
+
 @c *********************************************************************
 @node GNU Distribution
 @chapter GNU Distribution