Merge pull request #2 from darkmattercoder/darkmattercoder-patch-readmetypo

[bubblebox.git] / README.md

diff --git a/README.md b/README.md
index e63c4e23c1f7c89b48edd3d506c8b6e244936367..32aa2ec7165f7b35adb985ce8be41a1c9cb0c387 100644 (file)
--- a/README.md
+++ b/README.md
@@ -6,10 +6,13 @@ This is the documentation of [BubbleBox](https://www.ralfj.de/projects/bubblebox
 tool to easily sandbox Linux applications.
 
 The primary use-case for BubbleBox is running applications that you do not trust enough
 tool to easily sandbox Linux applications.
 
 The primary use-case for BubbleBox is running applications that you do not trust enough

-to give them full access to hour home directory, and in particular the secret keys stored there.
-In this regard it is similar to [firejail] and [bubblejail], but less powerful and in exchange hopefully easier to configure.
+to give them full access to your home directory, and in particular the secret keys stored there.

 BubbleBox is based on [bubblewrap] and [xdg-dbus-proxy] which do all of the heavy lifting.
 
 BubbleBox is based on [bubblewrap] and [xdg-dbus-proxy] which do all of the heavy lifting.
 

+The goals of this project are similar to [firejail], but I found firejail's configuration to be extremely hard to maintain and debug.
+BubbleBox is meant for people that are comfortable editing its Python source code to adjust it to their needs;
+if you are looking for something with a more out-of-the-box experience, try [bubblejail].
+

 [firejail]: https://firejail.wordpress.com/
 [bubblejail]: https://github.com/igo95862/bubblejail
 [bubblewrap]: https://github.com/containers/bubblewrap
 [firejail]: https://firejail.wordpress.com/
 [bubblejail]: https://github.com/igo95862/bubblejail
 [bubblewrap]: https://github.com/containers/bubblewrap


@@ -26,8 +29,7 @@ in a BubbleBox checkout with contents like this:
 from bubblebox import *
 
 bubblebox(
 from bubblebox import *
 
 bubblebox(

-  profiles.DEFAULT,
-  profiles.DESKTOP,
+  profiles.DESKTOP("gamejail"),

   dbus_proxy_flags("--own=com.steampowered.*"),
 
   home_access({
   dbus_proxy_flags("--own=com.steampowered.*"),
 
   home_access({


@@ -53,18 +55,21 @@ The `profiles.py` file contains some useful directives that are needed by most a
 - `profiles.DEFAULT` adds the basic flags to isolate the sandbox from the environment
   by unsharing all namespaces except for the network.
   This profile gives access to `/usr`, `/sys`, and `/etc` and also creates a
 - `profiles.DEFAULT` adds the basic flags to isolate the sandbox from the environment
   by unsharing all namespaces except for the network.
   This profile gives access to `/usr`, `/sys`, and `/etc` and also creates a

-  stub file system inside the sandbox that is basically always required. It
-  assumes a merged-usr setup, e.g. it will add `/bin` as a symlink to
-  `/usr/bin`. It also gives read-only access to some files in the home directory
-  that are often needed to make a basic shell work: `.bashrc`, `.bash_aliases`,
-  `.profile` and the `bin` directory.
-- `profiles.DESKTOP` is intended to make GUI applications work. It provides
-  access to DRI, X11, ALSA, Wayland, and PulseAudio. Furthermore, some GUI
-  configuration files (`.XCompose`, fontconfig, and default mime-type
-  associations) are made available to the sandbox. This also sets up the D-Bus
-  proxy and gives the application access to notifications, screen saver control,
-  status icons, and the flatpak portals (however, actually using these portals
-  is untested and would likely require further integration). Finally, it makes
+  stub file system inside the sandbox that is basically always required, such as
+  an empty folder to serve as XDG_RUNTIME_DIR. It assumes a merged-usr setup,
+  e.g. it will add `/bin` as a symlink to `/usr/bin`. It also gives read-only
+  access to some files in the home directory that are often needed to make a
+  basic shell work: `.bashrc`, `.bash_aliases`, `.profile` and the `bin`
+  directory.
+- `profiles.DESKTOP("name")` is intended to make GUI applications work. It
+  extends `DEFAULT` by providing access to DRI, X11, ALSA, Wayland, and
+  PulseAudio. Furthermore, some GUI configuration files (`.XCompose`,
+  fontconfig, and default mime-type associations) are made available to the
+  sandbox. The `"name"` is used to create an XDG_RUNTIME_DIR that will be shared
+  among all instances of this sandbox. This also sets up the D-Bus proxy and
+  gives the application access to notifications, screen saver control, status
+  icons, and the flatpak portals (however, actually using these portals is
+  untested and would likely require further integration). Finally, it makes

   clicking on links inside the sandbox work properly if your default browser is
   Firefox.
 
   clicking on links inside the sandbox work properly if your default browser is
   Firefox.
 


@@ -77,10 +82,7 @@ own sandboxes. Here are the key directives to use:
   to the home directory.
 - `bwrap_flags` allows passing flags directly to `bwrap`. This is rarely needed.
 - `dbus_proxy_flags` allows passing flags directly to `xdg-dbus-proxy`.
   to the home directory.
 - `bwrap_flags` allows passing flags directly to `bwrap`. This is rarely needed.
 - `dbus_proxy_flags` allows passing flags directly to `xdg-dbus-proxy`.

-  This is the typical way to provide access to given D-Bus names.
-- `shared_runtime_dir("name")` ensures that all instances of the sandbox with this
-  name have a shared XDG_RUNTIME_DIR. This is needed e.g. for VSCodium instances
-  to find each other. This must be declared *before* `profiles.DESKTOP`.
+  This is the typical way to provide access to additional D-Bus names.

 
 ## Source, License
 
 
 ## Source, License