DOCSEARCHbyAlgolia
Submit Docs

Bubblejail Documentation

repository·master·Indexed 19 days ago

https://github.com/igo95862/bubblejail

A sandboxing utility based on bubblewrap that provides strong isolation by creating separate home directories for every application instance. It features a CLI and GUI for managing instances, profiles, and services, offering a more secure alternative to Firejail. The tool includes support for various system resources (X11, Wayland, PulseAudio, network) and provides specific configuration guidance for distributions like Alpine Linux, Ubuntu, and Void Linux.

Tokens
10.6K
Snippets
34
Records
58
Agent score
66%

What's inside Bubblejail

  1. Understand Bubblejail core concepts

    master

    Bubblejail is a sandboxing tool based on bubblewrap designed to prevent accidental unsandboxed execution. It uses a distinct model compared to Firejail:

    • Instance: Represents a separate, isolated home directory. Every sandboxed application typically gets its own instance to ensure complete filesystem isolation.
    • Service: Represents specific system resources granted to a sandbox (e.g., pulse_audio for sound, network for internet access).
    • Profile: A predefined collection of services tailored for specific applications (e.g., a firefox profile).
    • services.toml: A configuration file within each instance that defines which services and resources the sandbox can access.

  2. Install recommended packages for Bubblejail on Alpine Linux

    master

    Alpine Linux packaging does not support optional dependencies, meaning some highly recommended packages are not automatically installed with Bubblejail. To ensure full functionality, manually install the following packages:

    • desktop-file-utils: Required to update the desktop entry cache and allow Bubblejail instances to be selected as default applications.
    • libnotify: Enables desktop notifications when a Bubblejail instance fails to start, preventing silent failures.
    # Example command to install recommended packages on Alpine
pkg add desktop-file-utils libnotify

  3. Regenerate desktop entries for changed run command behavior

    master

    The run command behavior has changed: Bubblejail no longer prepends the executable_name unless no arguments were passed during initialization. Desktop entry overwrites now preserve all arguments.

    To ensure your desktop entries work correctly with the new behavior, it is recommended to regenerate them using the generate-desktop-entry command.

    ```bash
bubblejail generate-desktop-entry --profile firefox Firefox

    Note: Firefox is the name of the instance and firefox is the name of the profile.

  4. Install Bubblejail manually using Meson

    master

    If a package is not available for your distribution, you can build and install Bubblejail manually using the Meson build system.

    Build Requirements

    • Python 3 (>= 3.11)
    • Jinja2
    • Meson
    • scdoc (optional, for man pages)

    Runtime Requirements

    • Python 3 (>= 3.11)
    • Python PyXDG
    • Python Tomli-W
    • Python cattrs
    • Bubblewrap (>= 0.5.0)
    • XDG D-Bus Proxy
    • Python Qt6
    • libseccomp
    • python-lxns

    Installation Steps

    1. Setup the build directory: meson setup build
    2. Enter the directory: cd build
    3. Compile: meson compile
    4. Install: sudo meson install

    To uninstall, run sudo ninja uninstall from the build directory.

    meson setup build
cd build
meson compile
sudo meson install

  5. Migrate configuration to the new services.toml format

    master

    Starting from version 0.3, Bubblejail changed the configuration file location and format. The old config.toml is replaced by services.toml located in the instance_name/ directory.

    While Bubblejail attempts an automatic conversion on the next invocation, comments will not be preserved. To manually convert your configuration:

    1. Copy config.toml to services.toml.
    2. Move all uncategorized keys (e.g., executable_name) under a [common] section.
    3. Convert service names from the services array into individual section headers (e.g., services = ['x11', 'network'] becomes [x11] and [network]).
    4. Remove the service. prefix from section names (e.g., [service.home_share] becomes [home_share]).
    # New format example (services.toml)
[common]
executable_name = "/usr/bin/firefox"

[wayland]
[network]
[pulse_audio]
[direct_rendering]

[home_share]
home_paths = [ "Downloads",]

  6. Quick start: Create and run a sandboxed instance via GUI

    master

    The easiest way to use Bubblejail is through the Bubblejail Configuration GUI:

    1. Install your target application (e.g., firefox).
    2. Launch Bubblejail Configuration.
    3. Click the 'Create instance' button.
    4. Select an existing profile (e.g., firefox).
    5. (Optional) Rename the instance.
    6. Click 'Create'.

    This process creates the isolated instance and automatically registers a new desktop entry for it.

  7. Understand the Bubblejail GUI architecture

    master

    The Bubblejail GUI is built using PyQt6 and follows a hierarchical widget structure to manage service configurations and instances.

    • BubblejailConfigApp: The main application controller that manages window state and switches between different views.
    • SelectInstanceWidget: The entry point view that lists existing instances and provides a way to create new ones.
    • InstanceEditWidget: A view used to edit the configuration of a specific instance. It dynamically generates ServiceWidget components based on the services available in the system.
    • CreateInstanceWidget: A view for setting up a new instance, allowing users to choose a profile (template) and provide an instance name.
    • ServiceWidget: A grouped UI component representing a single service. It contains multiple OptionWidget components corresponding to that service's settings.
    • OptionWidget: Specialized widgets for different data types (Boolean, String, Integer, List, etc.) used to capture service-specific configuration values.

  8. Configure Dbus name ownership for GTK applications

    master

    Dbus is now always proxied. Some GTK applications (e.g., transmission-gtk) may crash if they cannot acquire their required Dbus name ownership (e.g., com.transmissionbt.*).

    To resolve this, use the dbus_name setting under the [common] section in your services.toml to specify the required Dbus name.

  9. Reference: ServiceWidget lifecycle and conflicts

    master

    A ServiceWidget manages the UI for a BubblejailService. It has two primary states:

    • Enabled: The service is active and its settings are being edited.
    • Disabled: The service is inactive or in a conflict state. If a service conflicts with another enabled service (defined in service.conflicts), the widget is disabled and displays a warning message: ⚠ Service <name> conflicts with <conflicts>. ⚠.

    When a user clicks a service group, the InstanceEditWidget triggers refresh_conflicts() to re-evaluate the enabled/disabled status of all service widgets based on current selections.

  10. Handle Namespace Limits

    master

    The NamespacesLimits service allows you to restrict the number of namespaces available inside the sandbox.

    • Recursive Limits: Limits are applied recursively.
    • Blocking: Setting the limit to 0 blocks the creation of any new namespaces.
    • Unlocking: Setting the limit to -1 removes the limit.

  11. How ServiceContainer manages services

    master

    The ServiceContainer is the central orchestrator for sandboxed resources. It performs several key functions:

    1. Configuration Mapping: It uses cattrs to structure raw configuration dictionaries into typed ServicesConfig objects.
    2. Service Instantiation: It maps service names to BubblejailService classes using SERVICES_MAP.
    3. Conflict Detection: It checks the conflicts attribute of each service to ensure incompatible services (like network and slirp4netns) are not enabled simultaneously.
    4. Lifecycle Management: It provides iterators to access default services, all active services, and lifecycle hooks (post_init_hook and post_shutdown_hook) for all running services.

  12. Use the Bubblejail CLI subcommands

    master

    Bubblejail provides a command-line interface for managing sandboxed instances. The primary subcommands are run, create, list, edit, and generate-desktop-entry.

    To use the CLI, invoke the bubblejail command followed by one of these subcommands and its specific arguments.

    # Example usage patterns (conceptual)
bubblejail create <instance_name> --profile <profile_name>
bubblejail list --list-what instances
bubblejail edit <instance_name>
bubblejail run <instance_name> [args_to_instance]
bubblejail generate-desktop-entry <instance_name> --profile <profile_name>