Release v3.2
============

This release was mostly driven by the requirements of "CARE", a new
project based on PRoot that will be released publicly soon on
http://reproducible.io.  For information, "CARE" is the short for
"Comprehensive Archiver for Reproducible Execution".

Highlights
----------

+ Many bugs exposed by a couple of static code analyzers (Coverity,
  Clang, ...) and some test-suites (Linux Test Project, libuv, ...)
  are now fixed.

+ The "kompat" extension ("-k" option) can now emulate most of the
  kernel features that would be required by the guest system but that
  are not available on the host kernel.  For example, it can now make
  programs from Ubuntu 13.04 64-bit run on RedHat 5 64-bit without any
  further tweaks:

     rh5-64$ proot -k 3.8 -R ubuntu-13.04-64bit/ ...

+ On ARM and x86_64, the heap segment is now emulated with a regular
  memory mapping to ensure this former always exists.  This was
  required because some kernels might put a non-fixed memory mapping
  right after the regular heap when using some GNU ELF interpreters
  (ld.so) as loaders.  Without the heap segment emulation, some
  programs like Bash would crash because the heap can't grow anymore:

      bash: xmalloc: locale.c:73: cannot allocate 2 bytes (0 bytes allocated)

Miscellaneous
-------------

+ When using the "-R" option, the path to the guest rootfs is now
  bound into the guest rootfs itself.  This is required to run
  programs that search for their DSOs in /proc/self/maps, like VLC for
  instance.

+ When using the "-v" option with a level greater than 2, syscalls are
  now printed as strings instead of numbers, à la strace:

    $ proot -v 3 true
    [...]
    proot info: pid 29847: sysenter start: mmap(0x0, 0x2d141, 0x1, 0x2, 0x3, 0x0) [...]
    [...]

+ The article about the migration from ScratchBox2 is now publicly
  available:

    https://github.com/cedric-vincent/PRoot/blob/v3.2/doc/articles/howto_migrate_from_scratchbox2.txt

Internal changes
----------------

+ Tools based on PRoot (CARE, DepsTracker, ATOS, ...) can now easily
  replace the original command-line interface with their own
  command-line interface.

+ It is now possible to chain forged syscalls to a regular syscall.
  Search for "register_chained_syscall" in the sources for details.

+ A couple of new helpers are now visible from the extensions.

Thanks
------

+ Bug reports and tests: Corbin Champion, Maxence Dalmais, and Nicolas
  Cornu.

+ Static code analysis: Antoine Moynault and Christophe Guillon.

+ Patches: Rémi Duraffort.

+ Unexpected hint: Christophe Monat :)

Validation
----------

====================  =================  ==============  =================  =========
testsuite                   host distro    guest distro           features   comments
====================  =================  ==============  =================  =========
proot-v3.2                 OBS */x86_64            none                N/A          a
proot-v3.2                    OBS */x86            none                N/A          a
proot-v3.2             Ubuntu-10.10/arm            none               none          a

proot-v3.2            Slack-14.0/x86_64            none               none          a
proot-v3.2            Slack-14.1/x86_64            none            seccomp          a

proot-v3.2/memcheck   Slack-14.1/x86_64            none               none          a
proot-v3.2/memcheck   Slack-14.1/x86_64            none            seccomp          a

proot-v3.2/asan       Slack-14.1/x86_64            none               none          a
proot-v3.2/asan       Slack-14.1/x86_64            none            seccomp          a

proot-v3.2/talleak    Slack-14.0/x86_64            none               none          a
proot-v3.2/talleak    Slack-14.1/x86_64            none            seccomp          a

libuv-0.10.18         Slack-14.0/x86_64    same as host               none          b
libuv-0.10.18         Slack-14.0/x86_64    same as host             kompat       b, c
libuv-0.10.18         Slack-14.1/x86_64    same as host            seccomp          a
libuv-0.10.18         Slack-14.1/x86_64    same as host     seccomp/kompat          b

libuv-0.10.18         Slack-14.0/x86_64  Slack-14.0/x86               none          b
libuv-0.10.18         Slack-14.0/x86_64  Slack-14.0/x86             kompat       b, c
libuv-0.10.18         Slack-14.1/x86_64  Slack-14.0/x86            seccomp          a
libuv-0.10.18         Slack-14.1/x86_64  Slack-14.0/x86     seccomp/kompat          b

ltp-syscall-20130904  Slack-14.0/x86_64    same as host               none          d
ltp-syscall-20130904  Slack-14.0/x86_64    same as host             kompat       d, e
ltp-syscall-20130904  Slack-14.1/x86_64    same as host            seccomp          d
ltp-syscall-20130904  Slack-14.1/x86_64    same as host     seccomp/kompat          e

ltp-syscall-20130904  Slack-14.0/x86_64  Slack-14.0/x86               none       d, f
ltp-syscall-20130904  Slack-14.0/x86_64  Slack-14.0/x86             kompat    d, e ,f
ltp-syscall-20130904  Slack-14.1/x86_64  Slack-14.0/x86            seccomp       d, f
ltp-syscall-20130904  Slack-14.1/x86_64  Slack-14.0/x86     seccomp/kompat    d, e, f

perl-5.18.1           Slack-14.0/x86_64    same as host               none          h
perl-5.18.1           Slack-14.0/x86_64    same as host             kompat       h, i
perl-5.18.1           Slack-14.1/x86_64    same as host            seccomp          h
perl-5.18.1           Slack-14.1/x86_64    same as host     seccomp/kompat          h

perl-5.18.1           Slack-14.0/x86_64  Slack-14.0/x86               none          h
perl-5.18.1           Slack-14.0/x86_64  Slack-14.0/x86             kompat       h, i
perl-5.18.1           Slack-14.1/x86_64  Slack-14.0/x86            seccomp          h
perl-5.18.1           Slack-14.1/x86_64  Slack-14.0/x86     seccomp/kompat          h

posixtestsuite-1.5.2  Slack-14.0/x86_64    same as host               none          a
posixtestsuite-1.5.2  Slack-14.0/x86_64    same as host             kompat          a
posixtestsuite-1.5.2  Slack-14.1/x86_64    same as host            seccomp          a
posixtestsuite-1.5.2  Slack-14.1/x86_64    same as host     seccomp/kompat          a

posixtestsuite-1.5.2  Slack-14.0/x86_64  Slack-14.0/x86               none          j
posixtestsuite-1.5.2  Slack-14.0/x86_64  Slack-14.0/x86             kompat          j
posixtestsuite-1.5.2  Slack-14.1/x86_64  Slack-14.0/x86            seccomp          j
posixtestsuite-1.5.2  Slack-14.1/x86_64  Slack-14.0/x86     seccomp/kompat          j

perl-5.16.1           Slack-14.0/x86_64  Slack-14.0/ARM         qemu-1.6.1          h
coreutils-8.19        Slack-14.0/x86_64  Slack-14.0/ARM         qemu-1.6.1          k

performance           Slack-14.0/x86_64            none               none          l
====================  =================  ==============  =================  =========

Comments
--------

a: everything is OK

b: failures:

   - "signal_multiple_loops" (ptrace slowdown -> timeout)

c: failures:

   - "threadpool_cancel_getaddrinfo" (need investigation)

d: failures:

   - "creat07", "execve04" (due to the usage of a loader in PRoot)

   - "ptrace01", "ptrace02", "ptrace03", "ptrace05" (no ptrace
     emulation in PRoot)

   - "rmdir02" (reach the PATH_MAX limit in PRoot)

   - "mremap03", "msync05", "pwrite03", "pwrite03_64" (due to heap
     emulation in PRoot)

   - "msgctl10", "msgctl11", (ptrace slowdown -> timeout)

e: failures:

   - "eventfd2_03", "pselect01", "pselect01_64" (known limitation of
     the "kompat" extension in PRoot)

f: failures:

   - "modify_ldt01" (need investigation)

h: failures:

   - "cpan/File-Path/t/Path.t",
     "dist/ExtUtils-Command/t/eu_command.t", "op/magic.t" (known
     failures due to PRoot)

i: failures:

   - parallel build is broken (need investigation)

j: failures:

   - "pthread_attr_setdetachstate", "pthread_attr_getdetachstate",
     "pthread_attr_init" (need investigation)

k: failures:

   - "misc/ls-misc", "misc/printenv", "split/fail",
     "df/total-unprocessed", "dd/skip-seek", "dd/skip-seek-past-file"
     (due to QEMU user-mode)

   - "install/basic-1", "mkdir/p-3", "readlink/can-e",
     "readlink/can-f", "readlink/can-m" (known failures due to PRoot)

l: performance regression introduced by commit 7863f562

Release v3.2
============

This release was mostly driven by the requirements of "CARE", a new
project based on PRoot that will be released publicly soon on
http://reproducible.io.  For information, "CARE" is the short for
"Comprehensive Archiver for Reproducible Execution".

Highlights
----------

+ Many bugs exposed by a couple of static code analyzers (Coverity,
  Clang, ...) and some test-suites (Linux Test Project, libuv, ...)
  are now fixed.

+ The "kompat" extension ("-k" option) can now emulate most of the
  kernel features that would be required by the guest system but that
  are not available on the host kernel.  For example, it can now make
  programs from Ubuntu 13.04 64-bit run on RedHat 5 64-bit without any
  further tweaks:

     rh5-64$ proot -k 3.8 -R ubuntu-13.04-64bit/ ...

+ On ARM and x86_64, the heap segment is now emulated with a regular
  memory mapping to ensure this former always exists.  This was
  required because some kernels might put a non-fixed memory mapping
  right after the regular heap when using some GNU ELF interpreters
  (ld.so) as loaders.  Without the heap segment emulation, some
  programs like Bash would crash because the heap can't grow anymore:

      bash: xmalloc: locale.c:73: cannot allocate 2 bytes (0 bytes allocated)

Miscellaneous
-------------

+ When using the "-R" option, the path to the guest rootfs is now
  bound into the guest rootfs itself.  This is required to run
  programs that search for their DSOs in /proc/self/maps, like VLC for
  instance.

+ When using the "-v" option with a level greater than 2, syscalls are
  now printed as strings instead of numbers, à la strace:

    $ proot -v 3 true
    [...]
    proot info: pid 29847: sysenter start: mmap(0x0, 0x2d141, 0x1, 0x2, 0x3, 0x0) [...]
    [...]

+ The article about the migration from ScratchBox2 is now publicly
  available:

    https://github.com/cedric-vincent/PRoot/blob/v3.2/doc/articles/howto_migrate_from_scratchbox2.txt

Internal changes
----------------

+ Tools based on PRoot (CARE, DepsTracker, ATOS, ...) can now easily
  replace the original command-line interface with their own
  command-line interface.

+ It is now possible to chain forged syscalls to a regular syscall.
  Search for "register_chained_syscall" in the sources for details.

+ A couple of new helpers are now visible from the extensions.

Thanks
------

+ Bug reports and tests: Corbin Champion, Maxence Dalmais, and Nicolas
  Cornu.

+ Static code analysis: Antoine Moynault and Christophe Guillon.

+ Patches: Rémi Duraffort.

+ Unexpected hint: Christophe Monat :)

Validation
----------

====================  =================  ==============  =================  =========
testsuite                   host distro    guest distro           features   comments
====================  =================  ==============  =================  =========
proot-v3.2                 OBS */x86_64            none                N/A          a
proot-v3.2                    OBS */x86            none                N/A          a
proot-v3.2             Ubuntu-10.10/arm            none               none          a

proot-v3.2            Slack-14.0/x86_64            none               none          a
proot-v3.2            Slack-14.1/x86_64            none            seccomp          a

proot-v3.2/memcheck   Slack-14.1/x86_64            none               none          a
proot-v3.2/memcheck   Slack-14.1/x86_64            none            seccomp          a

proot-v3.2/asan       Slack-14.1/x86_64            none               none          a
proot-v3.2/asan       Slack-14.1/x86_64            none            seccomp          a

proot-v3.2/talleak    Slack-14.0/x86_64            none               none          a
proot-v3.2/talleak    Slack-14.1/x86_64            none            seccomp          a

libuv-0.10.18         Slack-14.0/x86_64    same as host               none          b
libuv-0.10.18         Slack-14.0/x86_64    same as host             kompat       b, c
libuv-0.10.18         Slack-14.1/x86_64    same as host            seccomp          a
libuv-0.10.18         Slack-14.1/x86_64    same as host     seccomp/kompat          b

libuv-0.10.18         Slack-14.0/x86_64  Slack-14.0/x86               none          b
libuv-0.10.18         Slack-14.0/x86_64  Slack-14.0/x86             kompat       b, c
libuv-0.10.18         Slack-14.1/x86_64  Slack-14.0/x86            seccomp          a
libuv-0.10.18         Slack-14.1/x86_64  Slack-14.0/x86     seccomp/kompat          b

ltp-syscall-20130904  Slack-14.0/x86_64    same as host               none          d
ltp-syscall-20130904  Slack-14.0/x86_64    same as host             kompat       d, e
ltp-syscall-20130904  Slack-14.1/x86_64    same as host            seccomp          d
ltp-syscall-20130904  Slack-14.1/x86_64    same as host     seccomp/kompat          e

ltp-syscall-20130904  Slack-14.0/x86_64  Slack-14.0/x86               none       d, f
ltp-syscall-20130904  Slack-14.0/x86_64  Slack-14.0/x86             kompat    d, e ,f
ltp-syscall-20130904  Slack-14.1/x86_64  Slack-14.0/x86            seccomp       d, f
ltp-syscall-20130904  Slack-14.1/x86_64  Slack-14.0/x86     seccomp/kompat    d, e, f

perl-5.18.1           Slack-14.0/x86_64    same as host               none          h
perl-5.18.1           Slack-14.0/x86_64    same as host             kompat       h, i
perl-5.18.1           Slack-14.1/x86_64    same as host            seccomp          h
perl-5.18.1           Slack-14.1/x86_64    same as host     seccomp/kompat          h

perl-5.18.1           Slack-14.0/x86_64  Slack-14.0/x86               none          h
perl-5.18.1           Slack-14.0/x86_64  Slack-14.0/x86             kompat       h, i
perl-5.18.1           Slack-14.1/x86_64  Slack-14.0/x86            seccomp          h
perl-5.18.1           Slack-14.1/x86_64  Slack-14.0/x86     seccomp/kompat          h

posixtestsuite-1.5.2  Slack-14.0/x86_64    same as host               none          a
posixtestsuite-1.5.2  Slack-14.0/x86_64    same as host             kompat          a
posixtestsuite-1.5.2  Slack-14.1/x86_64    same as host            seccomp          a
posixtestsuite-1.5.2  Slack-14.1/x86_64    same as host     seccomp/kompat          a

posixtestsuite-1.5.2  Slack-14.0/x86_64  Slack-14.0/x86               none          j
posixtestsuite-1.5.2  Slack-14.0/x86_64  Slack-14.0/x86             kompat          j
posixtestsuite-1.5.2  Slack-14.1/x86_64  Slack-14.0/x86            seccomp          j
posixtestsuite-1.5.2  Slack-14.1/x86_64  Slack-14.0/x86     seccomp/kompat          j

perl-5.16.1           Slack-14.0/x86_64  Slack-14.0/ARM         qemu-1.6.1          h
coreutils-8.19        Slack-14.0/x86_64  Slack-14.0/ARM         qemu-1.6.1          k

performance           Slack-14.0/x86_64            none               none          l
====================  =================  ==============  =================  =========

Comments
--------

a: everything is OK

b: failures:

   - "signal_multiple_loops" (ptrace slowdown -> timeout)

c: failures:

   - "threadpool_cancel_getaddrinfo" (need investigation)

d: failures:

   - "creat07", "execve04" (due to the usage of a loader in PRoot)

   - "ptrace01", "ptrace02", "ptrace03", "ptrace05" (no ptrace
     emulation in PRoot)

   - "rmdir02" (reach the PATH_MAX limit in PRoot)

   - "mremap03", "msync05", "pwrite03", "pwrite03_64" (due to heap
     emulation in PRoot)

   - "msgctl10", "msgctl11", (ptrace slowdown -> timeout)

e: failures:

   - "eventfd2_03", "pselect01", "pselect01_64" (known limitation of
     the "kompat" extension in PRoot)

f: failures:

   - "modify_ldt01" (need investigation)

h: failures:

   - "cpan/File-Path/t/Path.t",
     "dist/ExtUtils-Command/t/eu_command.t", "op/magic.t" (known
     failures due to PRoot)

i: failures:

   - parallel build is broken (need investigation)

j: failures:

   - "pthread_attr_setdetachstate", "pthread_attr_getdetachstate",
     "pthread_attr_init" (need investigation)

k: failures:

   - "misc/ls-misc", "misc/printenv", "split/fail",
     "df/total-unprocessed", "dd/skip-seek", "dd/skip-seek-past-file"
     (due to QEMU user-mode)

   - "install/basic-1", "mkdir/p-3", "readlink/can-e",
     "readlink/can-f", "readlink/can-m" (known failures due to PRoot)

l: performance regression introduced by commit 7863f562

Release v3.1
============

Command-line interface changes
------------------------------

+ The initial command is not search in "." anymore, unless the "./"
  prefix is specified or unless "." is in $PATH, as expected.

+ The "-B" and "-Q" options are obsoleted by the new "-R" option.
  This latter is equivalent to "-B -r", as there was actually no point
  at using the "-B" option without "-r".

+ A warning is now emitted when the rootfs is specified à la
  chroot(1), that is, without using "-r" or "-R".

The old command-line interface is not documented anymore, but it will
be still supported for a couple of releases.  Although, users are
strongly encouraged to switch to the new one:

        ======================   =================
        old CLI                  new CLI
        ======================   =================
        proot rootfs             proot -r rootfs
        proot -B rootfs          proot -R rootfs
        proot -B -r rootfs       proot -R rootfs
        proot -Q qemu rootfs     proot -R rootfs -q qemu
        proot -Q qemu -r rootfs  proot -R rootfs -q qemu
        =======================  =======================

Extensions
----------

+ The "kompat" extension ("-k" option) has been greatly enhanced.  For
  example, it can now make programs from Ubuntu 13.04 32-bit run on
  RedHat 5 64-bit:

     rh5-64$ proot -k 3.8 -R ubuntu-13.04-32bit/ ...

+ The "fake id0" extension ("-0" option) handles more syscalls:
  mknod(2), capset(2), setxattr(2), setresuid(2), setresgid(2),
  getresuid(2), and getresgid(2).

Miscellaneous
-------------

+ PRoot is now compiled with large file-system support (LFS), this
  make it works with 64-bit file-systems (eg. CIFS) on 32-bit
  platforms.

+ The special symbolic link "/proc/self/root" now points to the guest
  rootfs, that is, to the path specified by "-r" or "-R".  Just like
  with chroot(2), this symlink may be broken as the referenced host
  path likely does not exist in the guest rootfs.  Although, this
  symlink is typically used to know if a process is under a chroot-ed
  environment.

+ Under QEMU, LD_LIBRARY_PATH is not clobbered anymore when a guest
  program is launched by a host program.

+ When seccomp-filter is enabled, this release is about 8% faster than
  the previous one.

+ A couple of bugs reported by Scan Coverity are fixed.

Thanks
------

Special thanks to Stephan Hadamik, Jérôme Audu, and Rémi Duraffort for
their valuable help.

Release v3.1
============

Command-line interface changes
------------------------------

+ The initial command is not search in "." anymore, unless the "./"
  prefix is specified or unless "." is in $PATH, as expected.

+ The "-B" and "-Q" options are obsoleted by the new "-R" option.
  This latter is equivalent to "-B -r", as there was actually no point
  at using the "-B" option without "-r".

+ A warning is now emitted when the rootfs is specified à la
  chroot(1), that is, without using "-r" or "-R".

The old command-line interface is not documented anymore, but it will
be still supported for a couple of releases.  Although, users are
strongly encouraged to switch to the new one:

        ======================   =================
        old CLI                  new CLI
        ======================   =================
        proot rootfs             proot -r rootfs
        proot -B rootfs          proot -R rootfs
        proot -B -r rootfs       proot -R rootfs
        proot -Q qemu rootfs     proot -R rootfs -q qemu
        proot -Q qemu -r rootfs  proot -R rootfs -q qemu
        =======================  =======================

Extensions
----------

+ The "kompat" extension ("-k" option) has been greatly enhanced.  For
  example, it can now make programs from Ubuntu 13.04 32-bit run on
  RedHat 5 64-bit:

     rh5-64$ proot -k 3.8 -R ubuntu-13.04-32bit/ ...

+ The "fake id0" extension ("-0" option) handles more syscalls:
  mknod(2), capset(2), setxattr(2), setresuid(2), setresgid(2),
  getresuid(2), and getresgid(2).

Miscellaneous
-------------

+ PRoot is now compiled with large file-system support (LFS), this
  make it works with 64-bit file-systems (eg. CIFS) on 32-bit
  platforms.

+ The special symbolic link "/proc/self/root" now points to the guest
  rootfs, that is, to the path specified by "-r" or "-R".  Just like
  with chroot(2), this symlink may be broken as the referenced host
  path likely does not exist in the guest rootfs.  Although, this
  symlink is typically used to know if a process is under a chroot-ed
  environment.

+ Under QEMU, LD_LIBRARY_PATH is not clobbered anymore when a guest
  program is launched by a host program.

+ When seccomp-filter is enabled, this release is about 8% faster than
  the previous one.

+ A couple of bugs reported by Scan Coverity are fixed.

Thanks
------

Special thanks to Stephan Hadamik, Jérôme Audu, and Rémi Duraffort for
their valuable help.

Release v3.0.2
==============

* Fix the search of the initial command: when the initial command is a
  symbolic link, PRoot has to dereference it in guest namespace, not
  in the host one.

* Return error code EACCESS instead of EISDIR when trying to execute a
  directory.  Some programs, such as "env", behave differently with
  respect to this error code.  For example:

      ### setup
      $ mkdir -p /tmp/foo/python
      $ export PATH=/tmp/foo:$PATH

      ### before (PRoot v2.3 ... v3.0.1)
      before$ proot env python
      env: python: Is a directory

      ### now (PRoot v3.0.2 ...)
      $ proot env python
      Python 2.7.5 (default, May 29 2013, 02:28:51)
      [GCC 4.8.0] on linux2
      Type "help", "copyright", "credits" or "license" for more information.
      >>>

Release v3.0.2
==============

* Fix the search of the initial command: when the initial command is a
  symbolic link, PRoot has to dereference it in guest namespace, not
  in the host one.

* Return error code EACCESS instead of EISDIR when trying to execute a
  directory.  Some programs, such as "env", behave differently with
  respect to this error code.  For example:

      ### setup
      $ mkdir -p /tmp/foo/python
      $ export PATH=/tmp/foo:$PATH

      ### before (PRoot v2.3 ... v3.0.1)
      before$ proot env python
      env: python: Is a directory

      ### now (PRoot v3.0.2 ...)
      $ proot env python
      Python 2.7.5 (default, May 29 2013, 02:28:51)
      [GCC 4.8.0] on linux2
      Type "help", "copyright", "credits" or "license" for more information.
      >>>

Release v3.0.1
==============

Fix support for bindings where the guest path is explicitly not
dereferenced.  Be careful, the syntax has changed:

        before$ proot -b /bin/bash:!/bin/sh

        now$ proot -b /bin/bash:/bin/sh!

Release v3.0.1
==============

Fix support for bindings where the guest path is explicitly not
dereferenced.  Be careful, the syntax has changed:

        before$ proot -b /bin/bash:!/bin/sh

        now$ proot -b /bin/bash:/bin/sh!

Release v3.0
============

New features
------------

* PRoot can now use the kernel feature named "seccomp-filter", a.k.a
  "seccomp mode 2", to improve its own performance significantly.  For
  examples, the tables below show the time overhead induced by PRoot
  compared to a native execution:

  - when generating the Perl 5.16.1 package:

    ===============  ===========  ==========
    command          seccomp off  seccomp on
    ===============  ===========  ==========
    ./configure.gnu          75%         25%
    make -j4                 70%         45%
    make -j4 check           25%          9%
    ===============  ===========  ==========

  - when generating the Coreutils 8.19 package:

    ===============  ===========  ==========
    command          seccomp off  seccomp on
    ===============  ===========  ==========
    ./configure              80%         33%
    make -j4                 75%         33%
    make -j4 check           80%          8%
    ===============  ===========  ==========

* It is now possible to explicitly not dereference the guest location
  of a binding by specifying ``!`` as the first character.  For
  instance::

      proot -b /bin/bash:!/bin/sh

  will not overlay ``/bin/dash`` when this latter is pointed to by
  ``/bin/sh`` (it's typically the case on Ubuntu and Debian).

Fix
---

* The initial command is not search in $PATH anymore when it starts
  with ``/`` or ``./``, and it doesn't exist.  For instance::

      $ rm test
      $ proot ./test
      proot warning: './test not found (root = /, cwd = /usr/local/cedric/git/proot)
      proot error: see `proot --help` or `man proot`.

Thanks
------

Many thanks to Will Drewry and Indan Zupancic, who made possible to
accelerate PTRACE_SYSCALL with seccomp-filter.  Also, thanks to Paul
Moore for his valuable set of seccomp tools.

Notes
-----

* Unlike what I said, this release is not shipped with a ptrace
  emulator.  It's planned for the next one, though.

* Seccomp-filter was first introduced in Linux 3.5 a year ago, it was
  also officially back-ported to Ubuntu 12.04 (Linux 3.2).  To know if
  PRoot is actually using this accelerator on your system, check the
  verbose output.  For intance::

    $ proot -v 1 true
    ...
    proot info: ptrace acceleration (seccomp mode 2) enabled
    ...

  But first, be sure it was built with this support::

    $ proot -V
    ...
    built-in accelerators: process_vm = yes, seccomp_filter = yes
    ...

Release v3.0
============

New features
------------

* PRoot can now use the kernel feature named "seccomp-filter", a.k.a
  "seccomp mode 2", to improve its own performance significantly.  For
  examples, the tables below show the time overhead induced by PRoot
  compared to a native execution:

  - when generating the Perl 5.16.1 package:

    ===============  ===========  ==========
    command          seccomp off  seccomp on
    ===============  ===========  ==========
    ./configure.gnu          75%         25%
    make -j4                 70%         45%
    make -j4 check           25%          9%
    ===============  ===========  ==========

  - when generating the Coreutils 8.19 package:

    ===============  ===========  ==========
    command          seccomp off  seccomp on
    ===============  ===========  ==========
    ./configure              80%         33%
    make -j4                 75%         33%
    make -j4 check           80%          8%
    ===============  ===========  ==========

* It is now possible to explicitly not dereference the guest location
  of a binding by specifying ``!`` as the first character.  For
  instance::

      proot -b /bin/bash:!/bin/sh

  will not overlay ``/bin/dash`` when this latter is pointed to by
  ``/bin/sh`` (it's typically the case on Ubuntu and Debian).

Fix
---

* The initial command is not search in $PATH anymore when it starts
  with ``/`` or ``./``, and it doesn't exist.  For instance::

      $ rm test
      $ proot ./test
      proot warning: './test not found (root = /, cwd = /usr/local/cedric/git/proot)
      proot error: see `proot --help` or `man proot`.

Thanks
------

Many thanks to Will Drewry and Indan Zupancic, who made possible to
accelerate PTRACE_SYSCALL with seccomp-filter.  Also, thanks to Paul
Moore for his valuable set of seccomp tools.

Notes
-----

* Unlike what I said, this release is not shipped with a ptrace
  emulator.  It's planned for the next one, though.

* Seccomp-filter was first introduced in Linux 3.5 a year ago, it was
  also officially back-ported to Ubuntu 12.04 (Linux 3.2).  To know if
  PRoot is actually using this accelerator on your system, check the
  verbose output.  For intance::

    $ proot -v 1 true
    ...
    proot info: ptrace acceleration (seccomp mode 2) enabled
    ...

  But first, be sure it was built with this support::

    $ proot -V
    ...
    built-in accelerators: process_vm = yes, seccomp_filter = yes
    ...

Release v2.4.1
==============

Fixes
-----

* Fix all warnings reported by GCC-4.8 "-Wall -Wextra" and Coverity
  Prevent 4.5.

* Fix Unix sockets path translation for some x86_64 systems.

* Make the "kompat" extension (-k option) work again.

* Fix spurious "can't delete /tmp/proot-$PID-XXXXX" messages.

Release v2.4.1
==============

Fixes
-----

* Fix all warnings reported by GCC-4.8 "-Wall -Wextra" and Coverity
  Prevent 4.5.

* Fix Unix sockets path translation for some x86_64 systems.

* Make the "kompat" extension (-k option) work again.

* Fix spurious "can't delete /tmp/proot-$PID-XXXXX" messages.

Release v2.4
============

New architectures
-----------------

* PRoot now works natively on Linux ARM64 systems (a.k.a AArch64).
  Note that PRoot/AArch64 doesn't support 32-bit binaries yet.

* PRoot/x86_64 now supports x32 binaries/rootfs.

Fixes
-----

* Paths from Unix domain sockets are now translated.  For example, it
  wasn't possible previously to use "tmux" in the guest rootfs if
  another instance were running in the host rootfs.

* When a host path is bound to a nonexistent guest path, PRoot tries
  to create this latter in the guest rootfs, for some technical
  reasons.  Previously, this "dummy" guest path was created with RWX
  permissions but this might cause troubles when re-using the rootfs
  for other purpose.  Now, this "dummy" guest path is created with
  minimal permissions, and it is also possible to avoid its creation
  by defining the PROOT_DONT_POLLUTE_ROOTFS environment variable.

Command-line interface changes
------------------------------

* The directory "/run" is removed from the list of recommended
  bindings (-B option) because this creates to much conflicts with
  programs that write in the "/run/var" directory.

* The -0 option now makes user's files appear as if they were actually
  owned by root, and it also fakes the success of any mode changes
  (chmod* syscalls).  This is typically useful to create packages
  where the files belong to the root user (it's almost always the
  case).

Internal changes
----------------

* PRoot should be even more portable now.  For instance, there's no
  need to worry about syscallee-saved registers anymore.

Thanks
------

This release was made possible thanks to, in no special order: Yvan
Roux, Jerôme Audu, Heehooman, Yann Droneaud, and James Le Cuirot.  See
"git log" for details.

Validation
----------

All the packages were built successfully on OBS.  The following tests
were ran on Slackware64 14.0 (and "current-130312" for x32) with QEMU
1.4.0.

=====================  ===========  =================  ==================
Guest distro           Options            Testsuite          Failures
=====================  ===========  =================  ==================
Slackware64 14.0                    PRoot-v2.4         OK
Slackware64 14.0       memcheck     PRoot-v2.4         OK
STLinux 2.4 SH4                     smoke tests        OK
Ubuntu 10.10 ARM                    PRoot-v2.4         OK
OpenEmbedded AArch64                smoke tests        OK
Slackware64 14.0       -r /         Perl 5.16.1        OK  2/2189  [1]_
Slackware64 14.0       -k 3.2.29    Perl 5.16.1        OK  2/2189  [1]_
Slackware 14.0 i486    -B           Perl 5.16.1        OK  3/2188  [2]_
Gentoo 20130130 x32    -B           Perl 5.16.1        OK  3/2188  [2]_
Slackware 14.0 ARM     -Q qemu-arm  Perl 5.16.1        OK  3/2188  [2]_
Slackware64 14.0       -r /         CoreUtils 8.19     OK  5/491   [3]_
Slackware64 14.0       -k 3.2.29    CoreUtils 8.19     OK  5/491   [3]_
Slackware 14.0 ARM     -Q qemu-arm  CoreUtils 8.19     OK  12/491  [4]_
Slackware64 14.0       -r /         POSIX tests 1.5.1  OK  same as native
Slackware 14.0 i486    -B           POSIX tests 1.5.1  OK  same as v2.3.1
Slackware 14.0 ARM     -Q qemu-arm  POSIX tests 1.5.1  OK  same as v2.3.1
=====================  ===========  =================  ==================

.. [1] not a regression: cpan/File-Path/t/Path.t,
       dist/ExtUtils-Command/t/eu_command.t

.. [2] not a regression: op/magic.t + [1]

.. [3] not a regression: install/basic-1, mkdir/p-3, readlink/can-e,
       readlink/can-f, readlink/can-m

.. [4] not a regression: misc/ls-misc, misc/printenv, split/fail,
       misc/stty, df/total-unprocessed, dd/skip-seek,
       dd/skip-seek-past-file, + [3]_

Release v2.4
============

New architectures
-----------------

* PRoot now works natively on Linux ARM64 systems (a.k.a AArch64).
  Note that PRoot/AArch64 doesn't support 32-bit binaries yet.

* PRoot/x86_64 now supports x32 binaries/rootfs.

Fixes
-----

* Paths from Unix domain sockets are now translated.  For example, it
  wasn't possible previously to use "tmux" in the guest rootfs if
  another instance were running in the host rootfs.

* When a host path is bound to a nonexistent guest path, PRoot tries
  to create this latter in the guest rootfs, for some technical
  reasons.  Previously, this "dummy" guest path was created with RWX
  permissions but this might cause troubles when re-using the rootfs
  for other purpose.  Now, this "dummy" guest path is created with
  minimal permissions, and it is also possible to avoid its creation
  by defining the PROOT_DONT_POLLUTE_ROOTFS environment variable.

Command-line interface changes
------------------------------

* The directory "/run" is removed from the list of recommended
  bindings (-B option) because this creates to much conflicts with
  programs that write in the "/run/var" directory.

* The -0 option now makes user's files appear as if they were actually
  owned by root, and it also fakes the success of any mode changes
  (chmod* syscalls).  This is typically useful to create packages
  where the files belong to the root user (it's almost always the
  case).

Internal changes
----------------

* PRoot should be even more portable now.  For instance, there's no
  need to worry about syscallee-saved registers anymore.

Thanks
------

This release was made possible thanks to, in no special order: Yvan
Roux, Jerôme Audu, Heehooman, Yann Droneaud, and James Le Cuirot.  See
"git log" for details.

Validation
----------

All the packages were built successfully on OBS.  The following tests
were ran on Slackware64 14.0 (and "current-130312" for x32) with QEMU
1.4.0.

=====================  ===========  =================  ==================
Guest distro           Options            Testsuite          Failures
=====================  ===========  =================  ==================
Slackware64 14.0                    PRoot-v2.4         OK
Slackware64 14.0       memcheck     PRoot-v2.4         OK
STLinux 2.4 SH4                     smoke tests        OK
Ubuntu 10.10 ARM                    PRoot-v2.4         OK
OpenEmbedded AArch64                smoke tests        OK
Slackware64 14.0       -r /         Perl 5.16.1        OK  2/2189  [1]_
Slackware64 14.0       -k 3.2.29    Perl 5.16.1        OK  2/2189  [1]_
Slackware 14.0 i486    -B           Perl 5.16.1        OK  3/2188  [2]_
Gentoo 20130130 x32    -B           Perl 5.16.1        OK  3/2188  [2]_
Slackware 14.0 ARM     -Q qemu-arm  Perl 5.16.1        OK  3/2188  [2]_
Slackware64 14.0       -r /         CoreUtils 8.19     OK  5/491   [3]_
Slackware64 14.0       -k 3.2.29    CoreUtils 8.19     OK  5/491   [3]_
Slackware 14.0 ARM     -Q qemu-arm  CoreUtils 8.19     OK  12/491  [4]_
Slackware64 14.0       -r /         POSIX tests 1.5.1  OK  same as native
Slackware 14.0 i486    -B           POSIX tests 1.5.1  OK  same as v2.3.1
Slackware 14.0 ARM     -Q qemu-arm  POSIX tests 1.5.1  OK  same as v2.3.1
=====================  ===========  =================  ==================

.. [1] not a regression: cpan/File-Path/t/Path.t,
       dist/ExtUtils-Command/t/eu_command.t

.. [2] not a regression: op/magic.t + [1]

.. [3] not a regression: install/basic-1, mkdir/p-3, readlink/can-e,
       readlink/can-f, readlink/can-m

.. [4] not a regression: misc/ls-misc, misc/printenv, split/fail,
       misc/stty, df/total-unprocessed, dd/skip-seek,
       dd/skip-seek-past-file, + [3]_

Release v2.3.1
==============

New feature
-----------

* The "fake id0" feature was improved by Rémi Duraffort in order to
  support privileged write operations in read-only files/directories.
  Some package managers (Fedora, Debian, ...) relies on this special
  behavior::

      # ls -ld /usr/lib
      dr-xr-xr-x 22 root root 40960 Jan  2 11:19 /usr/lib/
      # install -v something.so /usr/lib/
      removed ‘/usr/lib/something.so‘
      ‘something.so‘ -> ‘/usr/lib/something.so‘

Fixes
-----

* Fix bindings to a guest path that contains a symbolic link.  For
  example when the given guest path ``/var/run/dbus`` is a symbolic
  link to ``/run/dbus``.

* Fix a memory corruption when accessing files in "/proc/self/"

Special thanks to Rémi Duraffort for the improved "fake id0" feature
and for the bug reports.

Release v2.3.1
==============

New feature
-----------

* The "fake id0" feature was improved by Rémi Duraffort in order to
  support privileged write operations in read-only files/directories.
  Some package managers (Fedora, Debian, ...) relies on this special
  behavior::

      # ls -ld /usr/lib
      dr-xr-xr-x 22 root root 40960 Jan  2 11:19 /usr/lib/
      # install -v something.so /usr/lib/
      removed ‘/usr/lib/something.so‘
      ‘something.so‘ -> ‘/usr/lib/something.so‘

Fixes
-----

* Fix bindings to a guest path that contains a symbolic link.  For
  example when the given guest path ``/var/run/dbus`` is a symbolic
  link to ``/run/dbus``.

* Fix a memory corruption when accessing files in "/proc/self/"

Special thanks to Rémi Duraffort for the improved "fake id0" feature
and for the bug reports.

Release v2.3
============

This release is intended more specifically to developers and advanced
users, it was mostly driven by the requirements of an internal
STMicroelectronics project named "Auto-Tuning Optimization Service".

New features
------------

* There's now an extension mechanism in PRoot that allows developers
  to add their own features and/or to use PRoot as a Linux process
  instrumentation engine.  The two following old features were moved
  to this new extension interface: "-k *string*" and "-0"
  (respectively: set the kernel release and compatibility level to
  *string*"; and force some syscalls to behave as if executed by
  "root").

* It is now possible to execute PRoot under PRoot, well somewhat.
  Actually the initial instance of PRoot detects that it is being
  called again and recomputes the configuration for the new process
  tree.  This feature is still experimental and was way harder to
  implement than expected, however it was worth the effort since it
  enforced the consistency in PRoot.  Just one example among many, in
  PRoot the "chroot" feature is now really equivalent to the
  "mount/bind" one, that is, ``chroot path/to/rootfs`` is similar to
  ``mount --bind path/to/rootfs /``.

* The "current working directory" (chdir(2), getcwd(2), ...) is now
  fully emulated by PRoot.  Sadly a minor regression was introduced:
  even if the current working directory has been removed, getcwd(2)
  returns a "correct" value.  This should be fixed in the next
  release.

Command-line interface changes
------------------------------

* The message "proot info: started/exited" isn't printed by default
  anymore since it might introduce noise when PRoot is used inside a
  test-suite that compares outputs.  This message was initially added
  to know whether the guest program has exited immediately.

* The "-u" and "-W" options have disappeared.  The former wasn't
  really useful and the latter was definitely useless since the
  default "current working directory" is "." since v2.1, that means
  the three examples below are equivalent ("-W" was just an alias to
  "-b . -w .")::

      proot -b . [...]
      proot -b . -w . [...]
      proot -W [...]

Fixes
-----

* The option ``-w .`` is now really equivalent to ``-w $PWD``.

* A bug almost impossible to describe here has been fixed, it appeared
  only when specifying relative bindings, for instance: ``-b .``.

Internal changes
----------------

* PRoot now relies on Talloc: a hierarchical, reference counted memory
  pool system with destructors.  It is the core memory allocator used
  in Samba: http://talloc.samba.org.  This is definitely a worthwhile
  dependency for the sake of development scalability and
  debuggability.  For example, PRoot now has an explicit garbage
  collector (c.f. ``tracee->ctx``), and the full dynamic memory
  hierarchy can be printed by sending the USR1 signal to PRoot::

      native-shell$ proot --mount=$HOME --mount=/proc --rootfs=./slackware-14/
      prooted-shell$ kill -s USR1 $(grep Tracer /proc/self/status | cut -f 2)

      Tracee           0x6150c0  768 bytes  0 ref'    (pid = 22495)
          talloc_new: ./tracee/tracee.c:97 0x615420  0 bytes  0 ref'
          $exe             0x61bef0  10 bytes  0 ref'     ("/bin/bash")
          @cmdline         0x61bf60  16 bytes  0 ref'     ("/bin/sh", )
              /bin/sh          0x61bfd0  8 bytes  0 ref'
          $glue            0x61bae0  24 bytes  0 ref'     ("/tmp/proot-22494-UfGAPh")
          FileSystemNameSpace 0x615480  32 bytes  0 ref'
              $cwd             0x61b880  13 bytes  0 ref'     ("/home/cedric")
              Bindings         0x61b970  16 bytes  0 ref'     (host)
                  Binding          0x615570  8280 bytes  1 ref'   (/home/cedric:/home/cedric)
                  Binding          0x6176a0  8280 bytes  1 ref'   (/proc:/proc)
                  Binding          0x6197d0  8280 bytes  1 ref'   (/usr/local/proot/slackware-14:/)
              Bindings         0x61b900  16 bytes  0 ref'     (guest)
                  Binding          -> 0x6176a0
                  Binding          -> 0x615570
                  Binding          -> 0x6197d0

Release v2.3
============

This release is intended more specifically to developers and advanced
users, it was mostly driven by the requirements of an internal
STMicroelectronics project named "Auto-Tuning Optimization Service".

New features
------------

* There's now an extension mechanism in PRoot that allows developers
  to add their own features and/or to use PRoot as a Linux process
  instrumentation engine.  The two following old features were moved
  to this new extension interface: "-k *string*" and "-0"
  (respectively: set the kernel release and compatibility level to
  *string*"; and force some syscalls to behave as if executed by
  "root").

* It is now possible to execute PRoot under PRoot, well somewhat.
  Actually the initial instance of PRoot detects that it is being
  called again and recomputes the configuration for the new process
  tree.  This feature is still experimental and was way harder to
  implement than expected, however it was worth the effort since it
  enforced the consistency in PRoot.  Just one example among many, in
  PRoot the "chroot" feature is now really equivalent to the
  "mount/bind" one, that is, ``chroot path/to/rootfs`` is similar to
  ``mount --bind path/to/rootfs /``.

* The "current working directory" (chdir(2), getcwd(2), ...) is now
  fully emulated by PRoot.  Sadly a minor regression was introduced:
  even if the current working directory has been removed, getcwd(2)
  returns a "correct" value.  This should be fixed in the next
  release.

Command-line interface changes
------------------------------

* The message "proot info: started/exited" isn't printed by default
  anymore since it might introduce noise when PRoot is used inside a
  test-suite that compares outputs.  This message was initially added
  to know whether the guest program has exited immediately.

* The "-u" and "-W" options have disappeared.  The former wasn't
  really useful and the latter was definitely useless since the
  default "current working directory" is "." since v2.1, that means
  the three examples below are equivalent ("-W" was just an alias to
  "-b . -w .")::

      proot -b . [...]
      proot -b . -w . [...]
      proot -W [...]

Fixes
-----

* The option ``-w .`` is now really equivalent to ``-w $PWD``.

* A bug almost impossible to describe here has been fixed, it appeared
  only when specifying relative bindings, for instance: ``-b .``.

Internal changes
----------------

* PRoot now relies on Talloc: a hierarchical, reference counted memory
  pool system with destructors.  It is the core memory allocator used
  in Samba: http://talloc.samba.org.  This is definitely a worthwhile
  dependency for the sake of development scalability and
  debuggability.  For example, PRoot now has an explicit garbage
  collector (c.f. ``tracee->ctx``), and the full dynamic memory
  hierarchy can be printed by sending the USR1 signal to PRoot::

      native-shell$ proot --mount=$HOME --mount=/proc --rootfs=./slackware-14/
      prooted-shell$ kill -s USR1 $(grep Tracer /proc/self/status | cut -f 2)

      Tracee           0x6150c0  768 bytes  0 ref'    (pid = 22495)
          talloc_new: ./tracee/tracee.c:97 0x615420  0 bytes  0 ref'
          $exe             0x61bef0  10 bytes  0 ref'     ("/bin/bash")
          @cmdline         0x61bf60  16 bytes  0 ref'     ("/bin/sh", )
              /bin/sh          0x61bfd0  8 bytes  0 ref'
          $glue            0x61bae0  24 bytes  0 ref'     ("/tmp/proot-22494-UfGAPh")
          FileSystemNameSpace 0x615480  32 bytes  0 ref'
              $cwd             0x61b880  13 bytes  0 ref'     ("/home/cedric")
              Bindings         0x61b970  16 bytes  0 ref'     (host)
                  Binding          0x615570  8280 bytes  1 ref'   (/home/cedric:/home/cedric)
                  Binding          0x6176a0  8280 bytes  1 ref'   (/proc:/proc)
                  Binding          0x6197d0  8280 bytes  1 ref'   (/usr/local/proot/slackware-14:/)
              Bindings         0x61b900  16 bytes  0 ref'     (guest)
                  Binding          -> 0x6176a0
                  Binding          -> 0x615570
                  Binding          -> 0x6197d0

Release v2.2
============

* This release brings some critical fixes so an upgrade is highly
  recommended, especially on x86_64 and Ubuntu.

* PRoot is now a lot faster: the speed-up can be up to 50% depending
  on the kind of application.

* PRoot can now mount/bind files anywhere in the guest rootfs, even if
  the mount point has no parent directory (and/or can't be created).
  With previous versions of PRoot, that would created kinda black hole
  in the filesystem hierarchy that might bug some programs like "cpio"
  or "rpm".

  For example, with the previous version of PRoot::

       $ proot -b /etc/motd:/black/holes/and/revelations
       proot warning: can't create the guest path (binding) ...
       proot info: started

       $ find /black
       find: `/black: No such file or directory

       $ cat /black/holes/and/revelations
       Time has come to make things right -- Matthew Bellamy

  And now::

       $ proot -b /etc/motd:/black/holes/and/revelations
       proot info: started

       $ find /black
       /black
       /black/holes
       /black/holes/and
       /black/holes/and/revelations

       $ cat /black/holes/and/revelations
       Time has come to make things right -- Matthew Bellamy

* "/run" was added to the list of recommended bindings (-B/-Q).

* SH4 and ARM architectures are now officially supported.

Thanks
------

Huge thanks to Rémi DURAFFORT for all the tests, bug reports, fixes,
and for hosting http://proot.me.

Thanks to Thomas P. HIGDON for the advanced investigation on a really
tricky bug (red zone corruption).

Release v2.2
============

* This release brings some critical fixes so an upgrade is highly
  recommended, especially on x86_64 and Ubuntu.

* PRoot is now a lot faster: the speed-up can be up to 50% depending
  on the kind of application.

* PRoot can now mount/bind files anywhere in the guest rootfs, even if
  the mount point has no parent directory (and/or can't be created).
  With previous versions of PRoot, that would created kinda black hole
  in the filesystem hierarchy that might bug some programs like "cpio"
  or "rpm".

  For example, with the previous version of PRoot::

       $ proot -b /etc/motd:/black/holes/and/revelations
       proot warning: can't create the guest path (binding) ...
       proot info: started

       $ find /black
       find: `/black: No such file or directory

       $ cat /black/holes/and/revelations
       Time has come to make things right -- Matthew Bellamy

  And now::

       $ proot -b /etc/motd:/black/holes/and/revelations
       proot info: started

       $ find /black
       /black
       /black/holes
       /black/holes/and
       /black/holes/and/revelations

       $ cat /black/holes/and/revelations
       Time has come to make things right -- Matthew Bellamy

* "/run" was added to the list of recommended bindings (-B/-Q).

* SH4 and ARM architectures are now officially supported.

Thanks
------

Huge thanks to Rémi DURAFFORT for all the tests, bug reports, fixes,
and for hosting http://proot.me.

Thanks to Thomas P. HIGDON for the advanced investigation on a really
tricky bug (red zone corruption).