JuNest

[!IMPORTANT] Starting from Ubuntu 23.10+, unprivileged user namespaces has been restricted. If using JuNest within Ubuntu, you may need root privileges in order to enable it. Alternatively, you can access JuNest using the proot mode as described below.

The lightweight Arch Linux based distro that runs, without root privileges, on top of any other Linux distro.

<h1 align="center"> <a href="https://github.com/fsquillace/junest"><img alt="JuNest" width=250px src="https://cdn.rawgit.com/fsquillace/junest-logo/master/junest.svg"></a> </h1>

|Project Status|Donation|Communication| |:------------:|:------:|:-----------:| | | | |

Table of Contents

• Description
• Quickstart
• Installation
• Usage
• Advanced usage
• Internals
• Troubleshooting
• More documentation
• Contributing
• Donating
• Authors

Description

JuNest (Jailed User Nest) is a lightweight Arch Linux based distribution that allows the creation of disposable and partially isolated GNU/Linux environments within any generic GNU/Linux host OS and without requiring root privileges to install packages.

JuNest is built around pacman, the Arch Linux package manager, which allows access to a wide range of packages from the Arch Linux repositories.

The main advantages of using JuNest include:

• Install packages without root privileges.
• Create partially isolated environments in which you can install packages without risking mishaps on production systems.
• Access a wider range of packages, particularly on GNU/Linux distros with comparatively limited repositories (such as CentOS and Red Hat).
• Run on a different architecture from the host OS via QEMU.
• Available for x86_64 and arm architectures but you can build your own image from scratch too!
• All Arch Linux lovers can enjoy their favourite distro everywhere!

JuNest follows the Arch Linux philosophy.

How different is JuNest from Docker and Vagrant?

Although JuNest sounds similar to a virtualisation/Linux container-like system, JuNest is quite different from solutions like Docker or Vagrant. In fact, the purpose of JuNest is not to build a completely isolated environment but, conversely, to provide the ability to run programs as if they were running natively from the host OS. Almost everything is shared between the host OS and the JuNest sandbox (kernel, process subtree, network, mounting, etc) and only the root filesystem gets isolated (since the programs installed in JuNest need to reside elsewhere).

This allows interaction between processes belonging to both host OS and JuNest. For example, you can install the top command in JuNest and use it to monitor processes belonging to the host OS.

Installation

Dependencies

JuNest comes with a very short list of dependencies in order to be installed in most of GNU/Linux distributions. Before installing JuNest be sure that all dependencies are properly installed in your system:

• bash (>=4.0)
• GNU coreutils

Installation from git repository

Just clone the JuNest repo somewhere (for example in ~/.local/share/junest):

git clone https://github.com/fsquillace/junest.git ~/.local/share/junest
export PATH=~/.local/share/junest/bin:$PATH

Optionally you want to use the wrappers to run commands installed in JuNest directly from host:

export PATH="$PATH:~/.junest/usr/bin_wrappers"

Update your ~/.bashrc or ~/.zshrc to get always the wrappers available.

Installation using AUR (Arch Linux only)

If you are using an Arch Linux system you can, alternatively, install JuNest from the AUR repository. JuNest will be located in /opt/junest/

Quickstart

Setup environment

The first operation required is to install the JuNest environment in the location of your choice via JUNEST_HOME environment variable (it must contain an absolute path) which by default is ~/.junest:

junest setup

The script will download the image from the repository and will place it to the default directory ~/.junest.

Access to environment

JuNest uses the Linux namespaces (aka ns) as the default backend program. To access via ns just type:

junest

You can use the command sudo to acquire fakeroot privileges and install/remove packages.

Alternatively, you can access fakeroot privileges without using sudo all the time with the -f (or --fakeroot) option:

junest -f

Another execution mode is via Proot:

junest proot [-f]

There are multiple backend programs, each with its own pros/cons. To know more about the JuNest execution modes depending on the backend program used, see the Usage section below.

Run JuNest installed programs directly from host OS

Programs installed within JuNest can be accessible directly from host machine without entering into a JuNest session (namely, no need to call junest command first). For instance, supposing the host OS is an Ubuntu distro you can directly run pacman by simply updating the PATH variable:

export PATH="$PATH:~/.junest/usr/bin_wrappers"
sudoj pacman -S htop
htop

By default the wrappers use ns mode. To use the ns --fakeroot you can use the convenient command helper sudoj. For more control on backend modes you can use the JUNEST_ARGS environment variable too. For instance, if you want to run iftop with real root privileges:

sudoj pacman -S iftop
sudo JUNEST_ARGS="groot" iftop

Bin wrappers can be always recreated (e.g. in case for some reasons they get corrupted) with:

junest create-bin-wrappers -f

Bin wrappers are automatically generated each time they get installed inside JuNest. This only works for executables located in /usr/bin path. For executables in other locations (say /usr/mybinpath) you can only create wrappers manually by executing the command:

junest create-bin-wrappers --bin-path /usr/mybinpath

Obviously, to get access to the corresponding bin wrappers you will need to update your PATH variable accordingly:

export PATH="$PATH:~/.junest/usr/mybinpath_wrappers"

Install packages from AUR

In ns mode, you can easily install package from AUR repository using the already available yay command. In proot mode, JuNest does no longer support the building of AUR packages.

Remember that in order to build packages from AUR, base-devel package group is required first:

pacman -S base-devel

JuNest uses a modified version of sudo provided by junest/sudo-fake. And the original core/sudo package will be ignored (and must not be installed) during the installation of base-devel.

Have fun!

If you are new on Arch Linux and you are not familiar with pacman package manager visit the pacman rosetta page.

Usage

There are three different ways you can run JuNest depending on the backend program you decide to use.

Linux namespaces based

The Linux namespaces represents the default backend program for JuNest. The requirements for having Linux namespaces working are:

1. Kernel starting from Linux 3.8 allows unprivileged processes to create user and mount namespaces.
2. The Linux kernel distro must have the user namespace enabled.

In the last years, the majority of GNU/Linux distros have the user namespace enabled by default. This means that you do not need to have root privileges to access to the JuNest environment via this method. This wiki provides the state of the user namespace on several GNU/Linux distros.

In order to run JuNest via Linux namespaces:

• As normal user - Allow to make basic operations or install/remove packages with sudo command: junest ns or junest
• As fakeroot - Allow to install/remove packages: junest ns -f or junest -f

This mode is based on the fantastic bubblewrap command.

PRoot based

Proot represents a portable solution which allows unprivileged users to execute programs inside a sandbox and works well in most of GNU/Linux distros available.

In order to run JuNest via Proot:

• As normal user - Allow to make b