Repository files navigation

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

Project Status	Donation	Communication

Table of Contents

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

JuNest (Jailed User Nest) is a lightweight Arch Linux based distributionthat allows the creation of disposable and partially isolated GNU/Linux environmentswithin any generic GNU/Linux host OS and without requiring rootprivileges to install packages.

JuNest is built aroundpacman,the Arch Linux package manager, which allows accessto 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 forx86_64 andarm architectures but you can build your own image from scratch too!
• All Arch Linux lovers can enjoy their favourite distro everywhere!

JuNest follows theArch Linux philosophy.

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 isnot tobuild a completely isolated environment but, conversely, to provide the ability to runprograms as if they were running natively from the host OS. Almost everything is sharedbetween 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 thetop command in JuNest and use it to monitorprocesses belonging to the host OS.

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

• bash (>=4.0)
• GNU coreutils

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

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

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

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

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

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

The first operation required is to install the JuNest environment in thelocation of your choice viaJUNEST_HOME environment variable(it must contain an absolute path) which bydefault is~/.junest:

junest setup

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

JuNest uses the Linux namespaces (akans) as the default backend program. To access vians just type:

junest

You can use the commandsudo to acquire fakeroot privileges andinstall/remove packages.

Alternatively, you can access fakeroot privileges without usingsudo all thetime with the-f (or--fakeroot) option:

junest -f

Another execution mode is viaProot:

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 programused, see theUsage section below.

Programs installed within JuNest can be accessible directly from host machinewithout entering into a JuNest session(namely, no need to calljunest command first).For instance, supposing the host OS is an Ubuntu distro you can directlyrunpacman by simply updating thePATH variable:

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

By default the wrappers usens mode. To use thens --fakeroot you can use the convenient command helpersudoj.For more control on backend modes you can use theJUNEST_ARGS environment variable too.For instance, if you want to runiftop with real root privileges:

sudoj pacman -S iftopsudo JUNEST_ARGS="groot" iftop

Bin wrappers can be always recreated (e.g. in case for some reasons they getcorrupted) 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 createwrappers 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 toupdate yourPATH variable accordingly:

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

Inns mode, you can easily install package fromAUR repositoryusing the already availableyaycommand. Inproot 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 requiredfirst:

pacman -S base-devel

JuNest uses a modified version ofsudo provided byjunest/sudo-fake. And the originalcore/sudopackage will be ignored(and must not be installed) during the installation ofbase-devel.

If you are new on Arch Linux and you are not familiar withpacman package managervisit thepacman rosetta page.

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

TheLinux namespacesrepresents 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 createuser 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 namespaceenabled by default. This means that you do not need to have root privileges toaccess to the JuNest environment via this method.Thiswikiprovides 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 packageswithsudo command:junest ns orjunest
• As fakeroot - Allow to install/remove packages:junest ns -f orjunest -f

This mode is based on the fantasticbubblewrap command.

Proot represents a portablesolution which allows unprivileged users to execute programs inside a sandboxand works well in most of GNU/Linux distros available.

In order to run JuNest via Proot:

• As normal user - Allow to make basic operations:junest proot

• As fakeroot - Allow to install/remove packages:junest proot -f

Inproot mode, the minimum recommended Linux kernel for the host OS is 2.6.32 on x86 (64 bit)and ARM architectures. It is still possible to run JuNest on lower2.6.x host OS kernels but errors may appear, and some applications maycrash. For further information, read theTroubleshootingsection below.

This solution suits only for privileged users. JuNest provides the possibilityto run the environment viachroot program.In particular, it uses a special program calledGRoot, a small and portableversion ofarch-chrootwrapper, that allows to bind mount directories specified by the user, such as/proc,/sys,/dev,/tmp,/run/user/<id> and$HOME, beforeexecuting any programs inside the JuNest sandbox. In case the mounting will notwork, JuNest is even providing the possibility to run the environment directly viathe purechroot command.

In order to run JuNest viachroot solutions:

• As root viaGRoot - Allow to have fully root privileges inside JuNest environment (you need to be root for executing this):junest groot

• As root viachroot - Allow to have fully root privileges inside JuNest environment (you need to be root for executing this):junest root

The following table shows the capabilities that each backend program is able to perform:

You can build a new JuNest image from scratch by running the following command:

junest build [-n]

The script will create a directory containing all the essentialsfiles in order to make JuNest working properly (such aspacman andproot).The option-n will skip the final validation tests if they are not needed.Remember that the script to build the image must run in an Arch Linux OS witharch-install-scripts and the base-devel packages installed.To change the build directory just use theJUNEST_TEMPDIR (by default /tmp).

After creating the imagejunest-x86_64.tar.gz you can install it by running:

junest setup -i junest-x86_64.tar.gz

For more details, you can also take a look atjunest-builderthat contains the script and systemd service used for the automatic buildingof the JuNest image.

Related wiki page:

• How to build a JuNest image using QEMU

The following command will download the ARM JuNest image and will run QEMU incase the host OS runs onx86_64 architecture:

$>export JUNEST_HOME=~/.junest-arm$> junest setup -a arm$> junest proot -- uname -marmv7l

To bind a host directory to a guest location:

junest -b"--bind /home/user/mydata /mnt/mydata"

Or using proot arguments:

junest proot -b"-b /mnt/mydata:/home/user/mydata"

The option-b to provide options to the backend program will work with PRoot, Namespace and GRoot backend programs.Check out the backend program options by passing--help option:

junest [u|g|p] -b"--help"

Although JuNest has not been designed to be a complete container, it is even possible tovirtualize the process tree thanks to thesystemd container.The JuNest containter allows to run services inside the container that can bevisible from the host OS through the network.The drawbacks of this are that the host OS must use systemd as a service manager,and the container can only be executed using root privileges.

To boot a JuNest container:

sudo systemd-nspawn -bD~/.junest

Related wiki page:

• How to run junest as a container
• How to run services using Systemd

JuNest attempts first to run the executables in the host OS located in differentpositions (/usr/bin,/bin,/usr/sbin and/sbin).As a fallback it tries to run the same executable if it is available in the JuNestenvironment.

There is a periodic automation build of the JuNest images forx86_64 archonly.The JuNest image forarm architecture may not be always up to date becausethe build is performed manually.

There are static QEMU binaries included in JuNest image that allows to run JuNestin a different architecture from the host system. They are located in/opt/qemudirectory.

For Arch Linux related FAQs take a look at theGeneral troubleshooting page.

Q: Why do I get the following error when I try to install a package?

Cannot find the gzip binary required for compressing man and info pages.

A: JuNest comes with a very basic number of packages.In order to install AUR packages you need to install the package groupbase-devel firstthat contains all the essential packages for compiling from source code (such as gcc, make, patch, etc):

#> pacman -S base-devel

Remember to not installcore/sudo as it conflicts withjunest/sudo-fake package.

Q: In ns mode when installing package I get the following error:

warning: warning given when extracting /usr/file... (Can't set user=0/group=0 for/usr/file...)

A: This is because as fakeroot is not possible to set the owner/group offiles as root. The package will still be installed correctly even though thismessage is showed.

Q: Why I cannot install packages?

#> pacman -S lsofPackages (1): lsof-4.88-2Total Download Size:    0.09 MiBTotal Installed Size:   0.21 MiBerror: no servers configured for repository: coreerror: no servers configured for repository: communityerror: failed to commit transaction (no servers configured for repository)Errors occurred, no packages were upgraded.

A: You need simply to update the mirrorlist file according to your location:

# Uncomment the repository line according to your location#> nano /etc/pacman.d/mirrorlist#> pacman -Syy

Q: How do I find which package a certain file belongs to?

A: JuNest is a really small distro, therefore you frequently need to findthe package name for a certain file.pkgfile is an extremely useful packagethat allows you to detect the package of a given file.For instance, if you want to find the package name for the commandgetopt:

#> pacman -S pkgfile#> pkgfile --update$> pkgfile getopcore/util-linux

Alternatively, you can use directlypacman command only. Take a lookhere.

Q: Why do I get the error: "FATAL: kernel too old"?

A: This is because the binaries from the precompiled package arecompiled for Linux kernel 2.6.32. When JuNest is started without furtheroptions, it tries to run a shell from the JuNest chroot. The system sees thatthe host OS kernel is too old and refuses to start the shell.

The solution is to present a higher "fake" kernel version to the JuNestchroot. PRoot offers the-k option for this, and JuNest passes this optionon to PRoot when-p is prepended. For example, to fake a kernel version of3.10, issue the following command:

$> junest proot -b "-k 3.10"

As Arch Linux ships binaries for kernel version 2.6.32, the above error isnot unique to the precompiled package from JuNest. It will also appear whentrying to run binaries that were later installed in the JuNest chroot withthepacman command.

In order to check if an executable inside JuNest chroot is compatible withthe kernel of the host OS just use thefile command, for instance:

$> file ~/.junest/usr/bin/bashELF 64-bit LSB executable, x86-64, version 1 (SYSV), dynamically linked(uses shared libs), for GNU/Linux 2.6.32,BuildID[sha1]=ec37e49e7188ff4030052783e61b859113e18ca6, stripped

The output shows the minimum recommended Linux kernel version.

Q: Why do I get the warning: "kompat: this kernel doesn't support privatefutexes and PRoot can't emulate them."?

A: This happens on older host OS kernels when the trick of showing a fakekernel version to the JuNest chroot is applied (see above:Kernel too old).

The consequence of showing a fake kernel version to the JuNest chroot is thatin the background, PRoot needs to translate requests from applications in thechroot to the old kernel of the host OS. Some of the newer kernelfunctionality can be emulated, but private futexes cannot be translated.

Private Futexes were introduced in Linux kernel 2.6.22. Therefore, the aboveproblem likely appears on old Linux systems, for example RHEL5 systems, whichare based on Linux kernel 2.6.18. Many of the core tools likewhich,man,orvim run without problems while others, especially XOrg-based programs,are more likely to show the warning. These are also more likely to crashunexpectedly.

Currently, there is no (easy) workaround for this. In order to be fullycompatible with kernels below 2.6.22, both the precompiled package fromJuNest and all software that is installed later needs to be compiled for thiskernel. Most likely this can only be achieved by building the needed softwarepackages from source, which kind of contradicts JuNest's distro-in-a-distrophilosophy.

Q: Why I do not have permissions for ping?

$> ping www.google.comping: icmp open socket: Operation not permitted

A: The ping command usessuid permissions that allow to execute the command usingroot privileges. The fakeroot mode is not able to execute a command set with suid,and you may need to use root privileges. There are other few commands thathavesuid permission, you can list the commands from your JuNest environmentwith the following command:

$> find /usr/bin -perm /4000

Q: Why I do not see any characters in the application I have installed?

A: This is probably because there are nofonts installed inthe system.

To quick fix this, you can just install a fonts package:

#> pacman -S gnu-free-fonts

Q: Why do I get warning when I install a package using root privileges?

#> pacman -S systat...warning: directory ownership differs on /usr/filesystem: 1000:100  package: 0:0...

A: In these cases the package installation went smoothly anyway.This should happen every time you install package with root privilegessince JuNest will try to preserve the JuNest environment by assigning ownershipof the files to the real user.

Q: Why do I get this warning when I run JuNest via Linux namespaces?

$> junest nsUnprivileged user namespace is disabled at kernel compile time or kernel too old (<3.8). Proceeding anyway...

A: This means that JuNest detected that the host OS eitherdoes not have a newer kernel version or the unprivileged user namespaceis not enabled at kernel compile time.JuNest does not stop the execution of the program but it attempts to run itanyway. Try to use Proot as backend program in case is not possible to invoke namespaces.

Q: Why do I get this warning when I run JuNest via Linux namespaces?

$> junest nsUnprivileged user namespace disabled. Root permissions are required to enable it: sudo sysctl kernel.unprivileged_userns_clone=1

A: This means that JuNest detected that the host OS eitherdoes not have a newer Linux version or the user namespace is not enabled.JuNest does not stop the execution of the program but it attempts to run itanyway. If you have root permissions try to enable it, otherwise try to useProot as backend program.

There are additional tutorials in theJuNest wiki page.

Contributions are welcome! You could help improving JuNest in the following ways:

• Reporting Bugs
• Suggesting Enhancements
• Writing Code

To sustain the project please consider funding by donations throughtheGitHub Sponsors page.

JuNest was originally created in late 2014 byFilippo Squillace (feel.sqoox@gmail.com).

Here is a list ofreally appreciated contributors!