source: general/sysutils/bubblewrap.xml@ 2ec98b3

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
  <!ENTITY % general-entities SYSTEM "../../general.ent">
  %general-entities;

  <!ENTITY bubblewrap-download-http "https://github.com/containers/bubblewrap/releases/download/v&bubblewrap-version;/bubblewrap-&bubblewrap-version;.tar.xz">
  <!ENTITY bubblewrap-download-ftp  " ">
  <!ENTITY bubblewrap-md5sum        "85f144f6c2c28c112abbcf98bedf6137">
  <!ENTITY bubblewrap-size          "120 KB">
  <!ENTITY bubblewrap-buildsize     "3.3 MB (with tests)">
  <!ENTITY bubblewrap-time          "less than 0.1 SBU (with tests)">
]>

<sect1 id="bubblewrap" xreflabel="bubblewrap-&bubblewrap-version;">
  <?dbhtml filename="bubblewrap.html"?>


  <title>Bubblewrap-&bubblewrap-version;</title>

  <indexterm zone="bubblewrap">
    <primary sortas="a-bubblewrap">bubblewrap</primary>
  </indexterm>

  <sect2 role="package">
    <title>Introduction to Bubblewrap</title>

    <para>
      <application>Bubblewrap</application> is a setuid implementation of user
      namespaces, or sandboxing, that provides access to a subset of kernel
      user namespace features. Bubblewrap allows user owned processes to run in
      an isolated environment with limited access to the underlying filesystem.
      <!-- Thanks for the reword DJ -->
    </para>

    &lfs122_checked;

    <bridgehead renderas="sect3">Package Information</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>
          Download (HTTP): <ulink url="&bubblewrap-download-http;"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Download (FTP): <ulink url="&bubblewrap-download-ftp;"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Download MD5 sum: &bubblewrap-md5sum;
        </para>
      </listitem>
      <listitem>
        <para>
          Download size: &bubblewrap-size;
        </para>
      </listitem>
      <listitem>
        <para>
          Estimated disk space required: &bubblewrap-buildsize;
        </para>
      </listitem>
      <listitem>
        <para>
          Estimated build time: &bubblewrap-time;
        </para>
      </listitem>
    </itemizedlist>

    <bridgehead renderas="sect3">Bubblewrap Dependencies</bridgehead>

    <bridgehead renderas="sect4">Optional</bridgehead>
    <para role="optional">
      <xref linkend="libxslt"/> (to generate manual pages),
      <xref linkend="libseccomp"/> (built with python bindings, for tests),
      <ulink url="https://github.com/scop/bash-completion">bash-completion</ulink>, and
      <ulink url="https://github.com/SELinuxProject/selinux">SELinux</ulink>
    </para>

  </sect2>

  <sect2 role="kernel" id="bubblewrap-kernel">
    <title>Kernel Configuration</title>

    <para>
      When this package began, upstream expected it could be installed
      suid-root. That was a long time ago, suid-root is generally considered
      a bad idea. As well as the default namespaces, this package requires the
      optional User namespace to be enabled. If that has not yet been enabled,
      select the following option in the kernel configuration and recompile the
      kernel:
    </para>

    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
      href="bubblewrap-kernel.xml"/>

    <indexterm zone="bubblewrap bubblewrap-kernel">
      <primary sortas="d-bubblewrap">bubblewrap</primary>
    </indexterm>
  </sect2>

  <sect2 role="installation">
    <title>Installation of Bubblewrap</title>

    <para>
      Install <application>Bubblewrap</application> by running the following
      commands:
    </para>

<screen><userinput>mkdir build &amp;&amp;
cd    build &amp;&amp;

meson setup --prefix=/usr --buildtype=release .. &amp;&amp;
ninja</userinput></screen>

    <para>
      Next, if you desire to run the test suite, fix an issue caused by the
      merged-/usr configuration in LFS:
    </para>

<screen remap="test"><userinput>sed 's@symlink usr/lib64@ro-bind-try /lib64@' -i ../tests/libtest.sh</userinput></screen>

    <para>
      To test the results, issue (as a user other than the
      <systemitem class="username">root</systemitem> user):
      <command>ninja test</command>
    </para>

    <para>
      Now, as the <systemitem class="username">root</systemitem> user:
    </para>

<screen role="root"><userinput>ninja install</userinput></screen>
  </sect2>

  <sect2 role="commands">
    <title>Command Explanations</title>

    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
      href="../../xincludes/meson-buildtype-release.xml"/>
  </sect2>

  <sect2 role="content">
    <title>Contents</title>

    <segmentedlist>
      <segtitle>Installed Program</segtitle>
      <segtitle>Installed Libraries</segtitle>
      <segtitle>Installed Directories</segtitle>

      <seglistitem>
        <seg>
          bwrap
        </seg>
        <seg>
          None
        </seg>
        <seg>
          None
        </seg>
      </seglistitem>
    </segmentedlist>

    <variablelist>
      <bridgehead renderas="sect3">Short Descriptions</bridgehead>
      <?dbfo list-presentation="list"?>
      <?dbhtml list-presentation="table"?>

      <varlistentry id="bwrap">
        <term><command>bwrap</command></term>
        <listitem>
          <para>
            generates a sandbox for a program to run in
          </para>
          <indexterm zone="bubblewrap bwrap">
            <primary sortas="b-bwrap">bwrap</primary>
          </indexterm>
        </listitem>
      </varlistentry>
    </variablelist>
  </sect2>

</sect1>