doc/TorBrowser/Sandbox/Linux.md

-= Linux Sandboxed Tor Browser Documentation =
+# Linux Sandboxed Tor Browser Documentation
 
    '''WARNING: This project is no longer maintained.  DO NOT EXPECT ANY FURTHER FIXES,
    INCLUDING SECURITY AND STOP USING THIS AS SOON AS POSSIBLE.'''
@@ -9,18 +9,18 @@
    '''WARNING: Active development is on indefinite hiatus.  DO NOT EXPECT ANY SIGNIFICANT
    NEW FEATURES OR IMPROVEMENTS'''.
 
-[[TOC]]
+
 
 The current efforts towards sandboxing Tor Browser on Linux are centered
-around `sandboxed-tor-browser` and [https://github.com/projectatomic/bubblewrap bubblewrap].
+around `sandboxed-tor-browser` and [bubblewrap](https://github.com/projectatomic/bubblewrap).
 
 Code: https://gitweb.torproject.org/tor-browser/sandboxed-tor-browser.git/
 
-'''Note: This documentation refers to the `master` git branch, which may be ahead of tagged revisions.'''
+**Note: This documentation refers to the `master` git branch, which may be ahead of tagged revisions.**
 
-== Dependencies ==
+## Dependencies
 
-=== Build ===
+### Build
 
 Building `sandboxed-tor-browser` requires:
 
@@ -29,7 +29,7 @@ Building `sandboxed-tor-browser` requires:
  * gb (https://getgb.io/)
  * Go (Tested with 1.7.x)
 
-=== Runtime ===
+### Runtime
 
 Running `sandboxed-tor-browser` requires:
 
@@ -40,7 +40,7 @@ Running `sandboxed-tor-browser` requires:
  * (Optional) The Adwaita Gtk+-2.0 theme (Install `gnome-themes-standard` on Ubuntu).
  * (Optional) libnotify
 
-=== Broken functionality ===
+### Broken functionality
 
 It is the aim to provide as much of the standard Tor Browser functionality
 as possible, while improving security.  However, some things are broken by
@@ -71,50 +71,51 @@ Functionality that must be explicitly allowed via configuration:
 
 New features will be judged on a case by case basis.
 
-== FAQ ==
+## FAQ
 
-=== Where do I get bubblewrap for my distribution? ===
+### Where do I get bubblewrap for my distribution?
 
-|| Distribution || Where ||
-|| Arch Linux || https://www.archlinux.org/packages/extra/x86_64/bubblewrap/ ||
-|| Debian (jessie) || https://packages.debian.org/jessie-backports/admin/bubblewrap ||
-|| Debian (stretch) || https://packages.debian.org/stretch/bubblewrap ||
-|| Fedora || https://admin.fedoraproject.org/pkgdb/package/rpms/bubblewrap/ ||
-|| Ubuntu || http://packages.ubuntu.com/yakkety/bubblewrap ||
+| Distribution | Where |
+|--------------|-------|
+| Arch Linux | https://www.archlinux.org/packages/extra/x86_64/bubblewrap/ |
+| Debian (jessie) | https://packages.debian.org/jessie-backports/admin/bubblewrap |
+| Debian (stretch) | https://packages.debian.org/stretch/bubblewrap |
+| Fedora | https://admin.fedoraproject.org/pkgdb/package/rpms/bubblewrap/ |
+| Ubuntu | http://packages.ubuntu.com/yakkety/bubblewrap |
 
-=== How do I check the hash/signature of the bundle archive? ===
+### How do I check the hash/signature of the bundle archive?
 
 `sandboxed-tor-browser` does that for you, with a hardcoded copy of
 the Tor Browser Developer's PGP key as part of the install process.
 
-=== Where are all my files? ===
+### Where are all my files?
 
 The Tor Browser process does not see all of your files, to prevent an
 attacker that has compromised your browser from reading them all.
 
 Improving the UI/UX surrounding this is a task for future versions.
 
-=== Where do my downloads go? ===
+### Where do my downloads go?
 
 By default `~/.local/share/sandboxed-tor-browser/tor-browser/Browser/Downloads`.
 This can be overridden (along with the `Desktop` directory) via the sandbox
 config when advanced options are enabled.
 
-=== How do I reinstall the browser? ===
+### How do I reinstall the browser?
 
-'''This will permanently delete your previous browser installation.'''
+**This will permanently delete your previous browser installation.**
 
 `sandboxed-tor-browser install`
 
-=== How do I reconfigure the tor or the sandbox? ===
+### How do I reconfigure the tor or the sandbox?
 
 `sandboxed-tor-browser config`
 
 Certain "advanced" options require: `sandboxed-tor-browser --advanced config`
 
-=== How do I get sound to work? ===
+### How do I get sound to work?
 
-'''WARNING: This is likely unsafe against sophisticated adversaries.'''
+**WARNING: This is likely unsafe against sophisticated adversaries.**
 
 As it stands right now, if PulseAudio is enabled in the sandbox, Firefox
 will get direct access to the host system's socket.  There are likely
@@ -133,7 +134,7 @@ For what it's worth, un-sandboxed Tor Browser also requires PulseAudio as
 of version 7.0, due to it being made a requirement for Firefox (See:
 https://bugzilla.mozilla.org/show_bug.cgi?id=1247056)
 
-=== The Circuit Display is missing! ===
+### The Circuit Display is missing!
 
 Unless it is explicitly enabled via the sandbox config, the Circuit Display
 is disabled, as that requires exposing more information to the firefox
@@ -142,18 +143,18 @@ process than would otherwise be needed.
 It should be disabled unless you are comfortable with the idea that firefox
 knows the IP address of your Guard or Bridges.
 
-=== "Check for Tor Browser Update..." is missing! ===
+### "Check for Tor Browser Update..." is missing!
 
 Making it work again is a task for a future version.  As of version 0.0.3-dev,
 updates are checked every 2 hours in the background and a notification is sent
 if your system supports it prompting you to restart the update.
 
-=== Are the fonts supposed to look different from normal? ===
+### Are the fonts supposed to look different from normal?
 
 To reduce fingerprinting, only the fonts that are bundled with Tor Browser
 are used to display content and the UI.
 
-=== Installing addons doesn't work, help! ===
+### Installing addons doesn't work, help!
 
 This is a bad idea for security and privacy reasons and is not supported at all.
 
@@ -161,13 +162,13 @@ As of version 0.0.11-dev, the sandbox takes extra steps to ensure that only
 addons that are bundled with Tor Browser by default are exposed to the container
 as a security measure.
 
-=== How do I edit the torrc? ===
+### How do I edit the torrc?
 
 That ability is not provided at this time.  The tor daemon launched
 by `sandboxed-tor-browser` uses it's own torrc and does not honor the
 one contained in the bundle directory.
 
-=== Wait, Firefox uses X11, isn't security basically hopeless? ===
+### Wait, Firefox uses X11, isn't security basically hopeless?
 
 Yes.  The current implementation of the sandbox does little to nothing
 to defend against Firefox doing evil things to or via the X socket.
@@ -188,9 +189,9 @@ will use is provided to enable easier nested X11 usage.
 the documentation doesn't make it obvious that such things are beyond
 the threat model.)
 
-=== How do I make this use a system tor instance? ===
+### How do I make this use a system tor instance?
 
-'''Using `sandboxed-tor-browser` in this way is not recommended.'''
+**Using `sandboxed-tor-browser` in this way is not recommended.**
 
 `TOR_CONTROL_PORT=9051 sandboxed-tor-browser`
 
@@ -198,12 +199,12 @@ the threat model.)
 
 `TOR_CONTROL_PORT=unix:///var/run/tor/control sandboxed-tor-browser`
 
-=== How do I disable the update check/auto update? ===
+### How do I disable the update check/auto update?
 
 You don't.  This software is for users that want extra security, and running
 out of date versions runs counter to that goal.
 
-=== How do I install Flash/Siverlight/etc? ===
+### How do I install Flash/Siverlight/etc?
 
 Your tears are delicious, and your plugins will burn.
 
@@ -211,7 +212,7 @@ More concretely, the sandbox only exposes system calls and shared libraries that
 are required for Tor Browser's functionality, and getting binary plugins to work
 would likely require loosening those restrictions.
 
-=== What happened to x86 (32 bit Intel) support? ===
+### What happened to x86 (32 bit Intel) support?
 
 While early revisions of the software including the 0.0.2 release supported x86,
 the decision was made to remove support due to several factors including reduced
@@ -220,17 +221,17 @@ resource limitations.
 
 See #20940 for more details.
 
-== Design Goals ==
+## Design Goals
 
- * Modern Linux kernels without `USER_NS` support '''MUST''' be capable of
+ * Modern Linux kernels without `USER_NS` support **MUST** be capable of
    supporting the sandboxed Tor Browser.
 
- * Proxy bypass '''MUST''' be impossible without a sandbox escape, even if the
+ * Proxy bypass **MUST** be impossible without a sandbox escape, even if the
    adversary gets RCE capability.
 
- * The firefox process's write access to the filesystem '''MUST''' be limited
+ * The firefox process's write access to the filesystem **MUST** be limited
    to the user preferences, download directory and the bookmarks.  The firefox
-   process's read access to the filesystem '''SHOULD''' be limited to the
+   process's read access to the filesystem **SHOULD** be limited to the
    Tor Browser installation directory.
 
    There is a UX tradeoff here in that, without access to at least the user's
@@ -238,17 +239,17 @@ See #20940 for more details.
    potentially malicious firefox executable can get at if it can read from
    the entire home directory.
 
- * The firefox process '''MUST NOT''' be responsible for launching the tor
-   instance.  The tor process '''MUST''' live in a separate sandbox, with no
-   access to user data (ie: tor '''MUST''' only be able to see it's `DataDir`).
+ * The firefox process **MUST NOT** be responsible for launching the tor
+   instance.  The tor process **MUST** live in a separate sandbox, with no
+   access to user data (ie: tor **MUST** only be able to see it's `DataDir`).
 
- * The firefox process '''MUST NOT''' be responsible for updating Tor Browser.
-   The downloads '''MUST''' be fetched over tor, and a more permissive sandbox
+ * The firefox process **MUST NOT** be responsible for updating Tor Browser.
+   The downloads **MUST** be fetched over tor, and a more permissive sandbox
    spawned to handle updating.
 
-== Implementation ==
+## Implementation
 
-=== `sandboxed-tor-browser` ===
+### `sandboxed-tor-browser`
 
 A user interface based on Gtk+ is provided to control installing/updating
 Tor Browser and to assist in configuring the tor daemon and sandbox.
@@ -257,7 +258,7 @@ Gtk+3.0 was used despite Tor Browser linking against 2.0 to avoid the need
 for a future migration.
 
 Files are placed in accordance with the
-[https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html XDG Base Directory specification],
+[XDG Base Directory specification](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html),
 honoring the appropriate overrides.
 
  * Config: `~/.config/sandboxed-tor-browser/`
@@ -265,7 +266,7 @@ honoring the appropriate overrides.
  * Tor `DataDir`: `~/.local/share/sandboxed-tor-browser/tor/`
  * Runtime files (eg: sockets): `/var/run/$UID/sandboxed-tor-browser/`
 
-==== Installer ====
+#### Installer
 
 `sandboxed-tor-browser` includes the capability to download and install the
 latest version of Tor Browser.
@@ -279,7 +280,7 @@ latest version of Tor Browser.
    installation with a hardcoded copy of the PGP key.
 
  * Modifies the bundle configuration post-install via writing out a set of
-   configuration files using the [https://developer.mozilla.org/en-US/Firefox/Enterprise_deployment Firefox Enterprise Deployment]
+   configuration files using the [Firefox Enterprise Deployment](https://developer.mozilla.org/en-US/Firefox/Enterprise_deployment)
    infrastructure.
 
    This is needed so that the built in auto updater, and addon updating can
@@ -287,7 +288,7 @@ latest version of Tor Browser.
    latter will not work by default due to filesystem permissions in the
    sandbox container.
 
-==== Updater ====
+#### Updater
 
 `sandboxed-tor-browser` handles keeping the installed bundle up to date,
 as the bundle directory is mounted read-only inside the firefox container
@@ -313,7 +314,7 @@ built in updater.
 
  * Re-installs the config overrides after each update.
 
-==== tor daemon interface ====
+#### tor daemon interface
 
 `sandboxed-tor-browser` can either use an existing tor daemon, or launch one
 in a sandbox container, and is responsible for routing traffic between the tor
@@ -341,7 +342,7 @@ and firefox sandbox containers (or the system tor and the firefox container).
    can use other applications with the sandboxed tor daemon (nb: Some
    weirdness with torsocks and the pass-through proxy, needs investigation.).
 
-==== Sandbox container launcher ====
+#### Sandbox container launcher
 
 `sandboxed-tor-browser` launches the various sandbox containers by `fork()`
 and `exec()`ing bubblewrap and passing it various arguments and static assets
@@ -361,6 +362,6 @@ interface code also includes:
 
  * Other misc routines for handling gtk+, PulseAudio, and other things.
 
-== Tickets ==
+## Tickets
 
 [[TicketQuery(component=Applications/Tor Browser Sandbox,order=id,status=!closed,format=table,col=id|summary|status|owner|keywords|severity|priority)]]