Skip to content

tutorial

Jump to bottom
parke edited this page Jan 4, 2022 · 32 revisions

Lxroot tutorials

Tutorial 1 - Use vland instead of lxroot

Introduction

  • While it is possible to use lxroot directly, I recommend learning to use vland before learning to use lxroot.
  • vland is a high-level convenience wrapper around Lxroot.
  • To learn about vland (as I recommend), please see the vland tutorial.
  • To learn about lxroot, please scroll down to tutorial 2.

Tutorial 2 - Install Lxroot

Introduction

  • In Tutorial 2, we will 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  unit
$  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 3 - Manually create an Alpine Linux guest userland

Introduction

  • Tutorial 3 continues from the end of tutorial 2.
  • In tutorial 3, we manually create an Alpine Linux guest userland.
  • A guest userland is simply a directory that contains the userland's files.
  • Tutorial 3 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 4 - Use Lxroot to enter the guest

Introduction

  • Tutorial 4 continues from the end of tutorial 3.
  • First, we run some basic commands that display information about host environment.
  • Then, we use the lxroot command to enter the guest.
  • Then, we run some basic commands in the guest that display information about the guest environment.
  • Then, we write the file /hello.txt in the guest environment.
  • Then, we exit the guest.
  • Finally, we remove the file ./guest/hello.txt from the host environment.

Commands

$  pwd
$  id
$  cat      /etc/issue
$  uname    -a
$  echo     'Hello, /hello.txt!'  >  /hello.txt
$  lxroot   -r  ./guest/
  #  pwd
  #  id
  #  cat    /etc/issue
  #  uname  -a
  #  ps     aux
  #  echo   'Hello, /hello.txt!'  >  /hello.txt
  #  exit
$  cat      ./guest/hello.txt
$  rm       ./guest/hello.txt

Commentary

  • Line 1 (pwd) displays the current working directory on the host.
  • Line 2 (id) displays the current process uid/gid on the host.
  • Line 3 (cat /etc/issue) displays the contents of /etc/issue on the host.
  • Line 4 displays kernel information on the host.
  • Line 5 attempts to write the file /hello.txt. This is expected to fail.
  • Line 6 runs lxroot to enter the guest.
  • The -r on line 6 tells lxroot to simulate uid = 0 (root).
    • Lines 7-13 (the indented lines) are run inside the guest.
    • Line 7 (pwd) displays the current working directory in the guest.
    • Line 8 (id) displays the current (possibly simulated) process uid/gid in the guest.
    • Line 9 displays the contents of /etc/issue in the guest.
    • Line 10 (uname -a) displays information about the kernel in the guest. The guest is running directly on the host's kernel, so the output of line 10 should be the same as the output of line 4.
    • Line 11 (ps aux) displays all the processes running in the guest. Specifically, these processes are running in the guest's process namespace.
    • Line 12 writes the file /hello.txt in the guest.
    • Line 13 (exit) exits the interactive shell that is running in the guest.
  • Line 14 runs cat ./guest/hello.txt on the host.
  • Line 15 removes the file ./guest/hello.txt on the host.

Tutorial 5 - Build Lxroot inside the guest

Introduction

  • Tutorial 5 continues from the end of tutorial 4.

Commands

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

Commentary

  • Line 1 runs apk update inside the guest as simulated root.
  • The -n option grants network access inside the guest.
  • The -r option simulates uid = 0 (root) inside the guest.
  • Line 2 installs basic build tools in the guest.
  • Lxroot's unit tests are written in Bash. Lxroot itself does not depend on Bash.
  • Line 3 runs an interactive shell inside the guest (without simulating uid = 0).
    • Lines 4-7 are run inside the guest.
    • Line 4 downloads the Lxroot source code.
    • Line 5 extracts the Lxroot source code.
    • Line 6 builds and tests Lxroot.
    • Line 7 exits the guest.

Tutorial 6 - Nest a second guest inside the first guest

Introduction

  • Tutorial 6 continues from the end of tutorial 5.
  • Tutorial 6 nests a second guest inside the first guest.
  • Inside the nested guest, we will create the file nested.txt.

Commands

$  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
  $  mkdir   nested_guest
  $  tar     xzf  alpine-minirootfs-3.15.0-x86_64.tar.gz  -C ./nested_guest/
  $  lxroot  -n  ./nested_guest/
    $  echo  'Hello, nested_guest!' > nested.txt
    $  cat   nested.txt
    $  exit
  $  cat     ./nested_guest/$HOME/nested.txt
  $  exit
$  cat       ./guest/$HOME/nested_guest/$HOME/nested.txt

Commentary

  • Line 1 enters the first guest userland.
    • Line 2 adds lxroot to your $PATH inside the first guest.
    • Line 3 downloads the Apline minirootfs tarball.
    • Line 4 creates the directory ./nested_guest/ that will contain the nested guest userland.
    • Line 5 extracts the tarball into the ./nested_guest/ directory.
    • Line 6 uses lxroot to run an interactive shell in the nested guest.
      • Line 7 writes Hello, nested guest! to the file nested.txt inside the nested guest.
      • Line 8 displays the contents of the nested.txt file inside the nested guest.
      • Line 9 exits the nested guest.
    • Line 10 displays the contents of the nested.txt file from the first guest.
    • Line 11 exits the first guest.
  • Line 12 displays the contents of the nested.txt file from the host.
Clone this wiki locally