man_page

Below is the output of lxroot --help-more.

usage:  lxroot  [mode] newroot  [options]  [-- command [arg ...]]

options
  -short                      one or more short options
  --long-option               a long option
  name=value                  set an environment variable
  [mode]  newroot             set and bind the newroot
  [mode]  path                bind a full or partial overlay
  'src'   [mode]  path        set the source for partial overlays
  'bind'  [mode]  dst  src    bind src to newroot/dst
  'cd'    path                cd to path (inside newroot)
  'wd'    path                cd to path and make path writable
  --                          end of options, command follows
  command  [arg ...]          command

MODES

  ra    read-auto  (default for newroot, described below)
  ro    read-only  (bind mount with MS_RDONLY)
  rw    read-write (bind mount without MS_RDONLY)

SHORT OPTIONS

  e     import (almost) all external environment variables
  n     allow network access (CLONE_NEWNET = 0)
  r     simulate root user (map uid and gid to zero)
  w     allow full write access to all read-auto binds
  x     allow X11 access (bind /tmp/.X11-unix and set $DISPLAY)

LONG OPTIONS

  --env           import (almost) all external environment variables
  --help          display help
  --help-more     display more help
  --network       allow network access (CLONE_NEWNET = 0)
  --pulseaudio    allow pulseaudio access (bind $XDG_RUNTIME_DIR/pulse)
  --root          simulate root user (map uid and gid to zero)
  --trace         log diagnostic info to stderr
  --version       print version info and exit
  --write         allow full write access to all read-auto binds
  --x11           allow X11 access (bind /tmp/.X11-unix and set $DISPLAY)

READ-AUTO MODE

The purpose of read-auto mode is to (a) grant a simulated-root user
broad or total write access, while (b) granting a non-root user write
access only to a few select directories, namely: $HOME, /tmp, and
/var/tmp.

To be precise and complete:

Each bind (including newroot) has a specified mode.  The specified
mode is one of: 'ra', 'ro', or 'rw'.

If no mode is specified for newroot, then newroot's specified mode
defaults to 'ra' (read-auto).

If any other bind lacks a specified mode, then that bind simply
inherits the specified mode of its parent.

Each bind also has an actual mode.  The actual mode is: 'ro' or 'rw'.

A bind's actual mode may be different from its specified mode.  A
bind's actual mode is determined as follows:

If the specified mode is 'rw', then the actual mode is 'rw'.

If the bind is inside a path specified by a wd-option, then the actual
mode is 'rw' (even if that bind's specified mode is 'ro').

If the specified mode is 'ra', and furthormore if:
  a)  the '-r' or '--root' option is specified, or
  b)  the '-w' or '--write' option is specified, or
  c)  the bind's destination path is inside $HOME, /tmp, or /var/tmp,
then the actual mode is 'rw'.

Otherwise the bind's actual mode is 'ro'.

NEWROOT

Note that the newroot, full-overlay, and partial-overlay options all
have the same form, namely:  [mode]  path

The first option of this form is the newroot-option.  The newroot-
option specfies the newroot.

If no newroot-option is specified, then lxroot will neither bind,
chroot, nor pivot.  This is useful to simulate root or deny network
access while retaining the current mount namespace.

FULL OVERLAY

Zero or more full-overlay options may occur anywhere before the first
set-source option.

A full-overlay option has the form:  [mode]  path

A full-overlay option will attempt to bind all the subdirectories
inside path to identically named subdirectories inside newroot.

For example, if my_overlay contains the subdirectories 'home', 'run',
and 'tmp', then the full-overlay option 'rw my_overlay' will attempt
to bind the following:

  my_overlay/home  to  newroot/home  in read-write mode
  my_overlay/run   to  newroot/run   in read-write mode
  my_overlay/tmp   to  newroot/tmp   in read-write mode

If any newroot/subdir does not exist, then that my_overlay/subdir will
be silently skipped.

SET SOURCE

A set-source option has the form:  'src'  [mode]  path

'src' is the literal string 'src'.

A set-source option sets the overlay-source-path and the default
overlay-mode.  These values will be used by any following
partial-overlay options.

Zero or more set-source options may be specified.

PARTIAL OVERLAY

Zero or more partial-overlay options may occur anywhere after the
first set-source option.

A partial-overlay option has the form:  [mode]  path

A partial-overlay option will bind overlay/path to newroot/path, where
overlay is the overlay-source-path set by the preceding set-source
option.

For example, the two options 'src my_overlay home/my_username' will do
the following:

  1)  first, the overlay-source-path will be set to 'my_overlay'
  2)  then, the following bind will occur:

        my_overlay/home/my_username  to  newroot/home/my_username

If either directory does not exist, lxroot will exit with status 1.

Successive partial-overlay options may be used to bind a selected
subset of the descendants of an overlay into newroot.  (Whereas a
single full-overlay option attempts to bind all of the full-overlay's
immediate subdirectories into newroot.)

BIND

A bind-option has the form:  'bind'  [mode]  dst  src

'bind' is the literal string 'bind'.

A bind-option will bind src to newroot/dst, using the optionally
specified mode.

Note that dst precedes src.  This hopefully improves readibilty in
scripts where: (a) many binds may be specified, (b) dst is tyically
shorter than src, and (c) src may vary greatly in length from bind to
bind.

CD

A cd-option has the form:  'cd'  path

'cd' is the literal string 'cd'.  One or zero cd-options may be
specified.

A cd-option tells lxroot to cd into path (in the new environment)
before executing the command.

path does not include newroot, as a cd-option is processed after the
pivot.

WD

A wd-option has the form:  'wd'  path

'wd' is the literal string 'wd'.  Zero or more wd-options may be
specified.

Lxroot will bind path (and all of path's descendants) in read-write
mode.  So a wd-option is used to make writeable a specific path (and
its descendants) inside the new environment.

path does not include newroot, as wd-options are processed after the
pivot.

Additionally, if no cd-option is specified, then lxroot will cd into
the path of the last wd-option prior to executing the command.

Note: Any path that is already mounted in read-only mode in the
outside environment (i.e. before lxroot runs) will still be read-only
inside the new environment.  This is because non-root namespaces can
only impose new read-only restricitons.  Non-root namespaces cannot
remove preexsiting read-only restrictions.

COMMAND

The command-option specifies the command that will be executed inside
the lxroot environment.  The command-option must be preceded by '--'.

If no command is specified, lxroot will attempt to find and execute an
interactive shell inside the lxroot environment.