bubblejail(1)

NAME

bubblejail - bubblewrap based sandboxing utility

SYNOPSIS

bubblejail <command> [--option] [args]

DESCRIPTION

Bubblejail's design is based on observations of Firejail's faults.

One of the biggest issues with Firejail is that you can accidentally run unsandboxed applications and not notice.

Bubblejail, instead of trying to transparently overlay an existing home directory, creates a separate home directory.

Every Instance represents a separate home directory. Typically, every sandboxed application has its own home directory.

Each instance has a services.toml file which defines the configuration of the instance such as system resources that the sandbox should have access to.

Service represents some system resources that the sandbox can be given access to. For example, the Pulse Audio service gives access to the Pulse Audio socket so that the application can use sound.

Profile is a predefined set of services that a particular application uses. For example, Firefox profiles gives access to network, pulse audio and ~/Downloads folder. Users can define their own profiles in $XDG_CONFIG_HOME/bubblejail/profiles directory.

Profiles also specify the desktop entry to copy and MIME types the application has.

Bubblejail uses TOML configuration format.

SUBCOMMANDS

  run [options...] [instance_name] [args_to_instance...]

Launch instance or run command inside.

The arguments are optional if you have executable_name key set in config.

Otherwise, you must specify arguments to run.

The arguments must include the program executable. Example:

    bubblejail run FirefoxInstance firefox google.com

If the instance already running this command will run the arguments inside the sandbox. If --wait option is passed the output of the command will be returned.

Options:

--debug-shell

    Opens a shell inside the sandbox instead of running program. Useful for debugging.

--dry-run

    Prints the bwrap and xdg-desktop-entry arguments instead of running.

--debug-helper-script <script_path>

    Use the specified helper script. This is mainly development command.

--debug-log-dbus

    Enables D-Bus proxy logging. By default the D-Bus proxy log is captured from the proxy and is parsed in to human readable format.

--wait

    Wait on the command inserted in to sandbox and get the output.

--debug-bwrap-args <bwrap_option> <bwrap_option_args>

    Add extra option to bwrap. First argument will be prefixed with `--`.

    The instance name must be separated with extra -- from the instance name.

    This option can be repeated multiple times for multiple args to bwrap.

    Example with adding capability and running as UID and GID 0 for test_instance instance:

        bubblejail run --debug-bwrap-args cap-add CAP_SYS_ADMIN --debug-bwrap-args uid 0 --debug-bwrap-args gid 0 -- test_instance

--wizard

    Enable configuration wizard. Can only be use if instance is not running.

  create [options...] [new_instance_name]

Create new bubblejail instance.

When a new instance is created a desktop entry will be also created.

Creating an instance from profile will print some import tips that you can use to import configuration from unsandboxed application.

Options:

--profile <profile>

    Bubblejail profile to use.

    If omitted an empty profile will be used and the user will have to define the configuration manually.

    There is also a generic profile which has some common settings such as network and windowing system access.

--no-desktop-entry

    Do not create desktop entry.

  list [list_what]

List certain bubblejail entities.

•   instances
•   profiles
•   services

  edit [instance_name]

Open instance config in $EDITOR.

After exiting the editor, the file is validated and only written if validation is successful.

EDITOR environmental variable must be set.

  generate-desktop-entry [options...] [instance_name]

Generate XDG desktop entry for an instance and place it in to the user's desktop entries folder. (usually at $XDG_DATA_HOME/applications folder) MIME database will also be updated after desktop entry is placed. Optional arguments can be used to specify a desktop entry to use as template. The desktop entry used as a template will have its Exec keys modified to run command inside the bubblejail instance.

Desktop entry can either be specified by profile, path, name or extracted from metadata when instance was created.

Options:

--profile <profile>

    Use desktop entry specified in profile.

--desktop-entry <name_or_path>

    Desktop entry name or absolute path to use as a template.

DIRECTORIES

  Bubblejail data directory

Bubblejail stores all data such as instances in a bubblejail directory located in the $XDG_DATA_HOME directory as specified by XDG Base Directory specification. By default Bubblejail's data directory can be found at $HOME/.local/share/bubblejail.

  Instance directories

Every instance is identified by a directory. Those instance directories can be found under instances folder in the Bubblejail data directory. The name of an instance directory serves as the unique name of an instance. For example, existence of $HOME/.local/share/bubblejail/instances/Firefox/ directory means that there is an instance named Firefox.

Instance directory has several important files and directories:

•   home: Instance's home directory.
•   services.toml: Instance's services configuration.

SEE ALSO

bubblejail.services(5)

Bubblejail home page: https://github.com/igo95862/bubblejail

BUGS

Report bugs to the bugtracker: https://github.com/igo95862/bubblejail/issues