tutorial

Lxroot tutorials

• Tutorial 1 - Install Lxroot
• Tutorial 2 - Manually create an Alpine Linux guest userland
• Tutorial 3 - Use Lxroot to enter the guest
• Tutorial 4 - Build Lxroot inside the guest
• Tutorial 5 - Nest a second guest inside the first guest
• See also: the vland tutorials

---

Tutorial 1 - Install Lxroot

Introduction

• In Tutorial 1, we install Lxroot by running the below commands.
• Root access is not required.

Commands

$  wget    -O lxroot.zip  https://github.com/parke/lxroot/archive/refs/heads/master.zip  
$  unzip   lxroot.zip
$  make    -C lxroot-master  test
$  export  PATH="$PATH:$PWD/lxroot-master/bin"
$  which   lxroot
$  lxroot  --help

Commentary

• Line 1 downloads the Lxroot source code as a zipfile.
• Line 2 unzips the source code.
• Line 3 builds and tests the lxroot command.
• Line 4 adds lxroot to your $PATH. (Alternatively, you may simply copy lxroot into your $PATH.)
• Line 5 verifies that lxroot is in your $PATH.
• Line 6 verifies that lxroot can run.

---

Tutorial 2 - Manually create an Alpine Linux guest userland

Introduction

• Tutorial 2 continues from the end of tutorial 1.
• In tutorial 2, we manually create an Alpine Linux guest userland.
• A guest userland is simply a directory that contains the userland's files.
• Tutorial 2 assumes your machine is x86_64. (If not, adjust accordingly.)

Commands

$  wget    https://dl-cdn.alpinelinux.org/alpine/v3.15/releases/x86_64/alpine-minirootfs-3.15.0-x86_64.tar.gz
$  mkdir   guest
$  tar     xzf  alpine-minirootfs-3.15.0-x86_64.tar.gz  -C ./guest/
$  ls      ./guest/
$  cp      -i  /etc/resolv.conf  ./guest/etc/
$  mkdir   -p  ./guest/$HOME

Commentary

• Line 1 downloads an Alpine Linux minirootfs tarball.
• Line 2 creates the ./guest/ directory that will contain the guest userland.
• Line 3 extracts the minirootfs tarball into the guest directory.
• Line 4 shows the contents of the guest directory.
• Line 5 copies /etc/resolv.conf into the guest directory.
• Line 6 makes a home directory in the guest directory.

---

Tutorial 3 - Use Lxroot to enter the guest

Introduction

• Tutorial 3 continues from the end of tutorial 2.
• In tutorial 3, we use the lxroot command to run an interactive shell in the guest.

Commands

$  lxroot  -n  -r  ./guest/
  #  pwd
  #  id
  #  cat   /etc/issue
  #  apk   update
  #  exit
$  pwd
$  id
$  cat  /etc/issue

Commentary

• Line 4 lxroots into the extracted directory.
• On line 4, -n grants network access inside the guest.
• On line 4 -r simulates UID = 0 (i.e. root) inside the guest.
• On line 4, -n and -r could be combined into -nr.
• Lines 5-9 (the indented lines) are run inside the guest userland.
• Line 9 exits the guest userland.
• Lines 10-11 are run on the host.

---

Tutorial 4 - Build Lxroot inside the guest

Introduction

• Tutorial 4 continues from the end of tutorial 3.

Commands

$  lxroot   -nr  ./guest/  --  apk  update
$  lxroot   -nr  ./guest/  --  apk  add  build-base
$  lxroot   -n   ./guest/
  $  pwd
  $  id
  $  wget   -O lxroot.zip  https://github.com/parke/lxroot/archive/refs/heads/master.zip  
  $  unzip  lxroot.zip
  $  make   -C lxroot-master  test
  #  exit

Commentary

• Line 1 runs apk update inside the guest as simulated root.
• Line 2 runs apk add build-base inside the guest as simulated root.
• Line 3 runs an interactive shell inside the guest.
• Lines 4-9 are run inside the guest.
  • Line 4 displays the current working directory.
  • Line 5 displays the process UID.
  • Line 6 downloads the Lxroot source code.
  • Line 7 extracts the Lxroot source code.
  • Line 8 builds and tests Lxroot.
  • Line 9 exits the guest.

---

Tutorial 5 - Nest a second guest inside the first guest

Introduction

• Tutorial 5 continues from the end of tutorial 5.
• Tutorial 5 nests a second guest inside the first guest.

Commands

$  id
$  lxroot    -n  ./guest/
  $  export  PATH="$PATH:$PWD/lxroot-master/bin"
  $  wget    https://dl-cdn.alpinelinux.org/alpine/v3.15/releases/x86_64/alpine-minirootfs-3.15.0-x86_64.tar.gz
  $  tar     xzf  alpine-minirootfs-3.15.0-x86_64.tar.gz
  $  mv      TODO  nested_guest
  $  id
  $  lxroot  -nr  ./nested_guest/
    #  id
    #  apk   update
    #  exit
  $  exit

Commentary

• Line 1 shows the process uid/gid on the host.
• Line 2 enters the guest userland.
• Line 3 adds lxroot to your PATH inside the guest.
• Line 4 downloads the Apline minirootfs tarball.
• Line 5 extracts the tarball.
• Line 6 renames the extracted directory to nested_guest for convenience.
• Line 7 shows the process uid/gid in the guest.
• Line 8 runs an interactive shell in the nested guest.
• Line 9 shows the process uid/gid in the nested guest.
• Line 10 runs apk update in the nested guest.
• Line 11 exits the nested guest.
• Line 12 exits the guest.

---

See also: the vland tutorials

• vland is a high-level convenience wrapper around Lxroot.
• Therefore, you may also wish to read the vland tutorials.