[patch] Patch in git format-patch email format

format-patch.eml (text/plain), 3.40 KB, created by Gil Kloepfer on 2024-04-26 01:12:32 UTC

From 674c0c4fe2879015b77fb193f2a4850a3d898594 Mon Sep 17 00:00:00 2001
From: Gil Kloepfer <[e-mail]>
Date: Thu, 25 Apr 2024 19:59:37 -0500
Subject: [PATCH] README.md:  Improve readability and provide guidance on
 documentation

Gentoo Bugzilla #930668:
While browsing README.md for sys-apps/sandbox, some of the text was
a bit awkward to read.  I (hopefully) improved this (see patch as part
of this report).  I also added a section on Documentation to the
README.md that will hopefully help address bug #462352 (or at least
point interested parties in the correct direction).
---
 README.md | 34 ++++++++++++++++++++++------------
 1 file changed, 22 insertions(+), 12 deletions(-)

diff --git a/README.md b/README.md
index 750c0fe..3b401bb 100644
--- a/README.md
+++ b/README.md
@@ -4,24 +4,24 @@ Sandbox is a library (and helper utility) to run programs in a "sandboxed"
 environment.  This is used as a QA measure to try and prevent applications from
 modifying files they should not.
 
-For example, in the Gentoo world we use it so we can build applications as root
-and make sure that the build system does not do crazy things outside of its
-build directory.  Such as install files to the live root file system or modify
-config files on the fly.
+For example, in the Gentoo world we use it to build applications as root
+while making sure that the build system does not do crazy things outside of its
+build directory (such as install files to the live root file system or modify
+config files on the fly).
 
 For people who are familiar with the Debian "fakeroot" project or the RPM based
 "InstallWatch", sandbox is in the same vein of projects.
 
 ## Method
 
-The way sandbox works is that you prime a few environment variables (in order
-to control the sandbox's behavior) and then stick it into the LD_PRELOAD
-variable.  Then when the ELF loader runs, it will first load the sandbox
-library.  Whenever an applications makes a library call that we have wrapped,
-we'll check the arguments against the environment settings.  Based on that, any
-access that is not permitted is logged and we return an error to the
-application.  Any access that is permitted is of course forwarded along to the
-real C library.
+Sandbox works by priming a few environment variables (in order to control
+the sandbox's behavior) then inserting its own libsandbox.so into
+the LD_PRELOAD variable.  This will cause the ELF loader to first load
+the sandbox library.  Whenever an application makes a library call that
+has been wrapped, the arguments will be checked against the environment
+settings.  Based on that, any access that is not permitted is logged and
+will return an error to the application.  Any access that is permitted
+will, of course, be forwarded along to the real C library.
 
 Static ELFs and setuid/setgid programs are executed with
 [ptrace()](https://man7.org/linux/man-pages/man2/ptrace.2.html) instead.
@@ -76,3 +76,13 @@ It requires:
   * [Linux](https://kernel.org/) 3.8+
 * C library
   * They all should work!
+
+## Documentation
+
+A manual page is not currently available, but a list of command-line options
+with descriptive text can be obtained by executing `sandbox --help`.
+
+Additional options are read from `/etc/sandbox.conf` and files in
+`/etc/sandbox.d/`.  A list of items that can appear in these files
+along with a description can be found in the `/etc/sandbox.conf` file
+that is included with the sandbox application.
-- 
2.43.2