From c7638f0655f6d0bc8b464e33a8e99fc01c6977a8 Mon Sep 17 00:00:00 2001 From: Filippo Squillace Date: Sat, 23 May 2015 18:51:46 +0000 Subject: [PATCH] Update the README --- README.md | 163 +++++++++++++++++++++++++++--------------------------- 1 file changed, 82 insertions(+), 81 deletions(-) diff --git a/README.md b/README.md index 1b8072b..7ea2d1b 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,11 @@ JuJube -==== -**JuJube**: the Arch Linux based distro that runs upon any Linux distros without root access +====== +The Arch Linux based distro that runs upon any Linux distros without root access [![Build status](https://api.travis-ci.org/fsquillace/jujube.png?branch=master)](https://travis-ci.org/fsquillace/jujube) Description ------------ +=========== **JuJube** is a lightweight Arch Linux based distribution that allows to have an isolated GNU/Linux environment inside any generic host GNU/Linux OS and without the need to have root privileges for installing packages. @@ -14,6 +14,7 @@ JuJube contains mainly the package managers (called pacman and yaourt) that allo to a wide range of packages from the Arch Linux repositories. The main advantages on using JuJube are: + - Install packages without root privileges. - Isolated environment in which you can install packages without affecting a production system. - Access to a wide range of packages in particular on GNU/Linux distros that may contain limited repositories (such as CentOS and RedHat). @@ -23,20 +24,14 @@ The main advantages on using JuJube are: JuJube follows the [Arch Linux philosophy](https://wiki.archlinux.org/index.php/The_Arch_Way). Quickstart ----------- +========== There are three different ways you can run JuJube: -- As normal user - Allow to make basic operations using [proot](https://wiki.archlinux.org/index.php/Proot): +- As normal user - Allow to make basic operations using [proot](https://wiki.archlinux.org/index.php/Proot): ```jujube``` - jujube +- As fakeroot - Allow to install/remove packages using [proot](https://wiki.archlinux.org/index.php/Proot): ```jujube -f``` -- As fakeroot - Allow to install/remove packages using [proot](https://wiki.archlinux.org/index.php/Proot): - - jujube -f - -- As root - Allow to have fully root privileges inside JuJube environment using [arch-chroot](https://wiki.archlinux.org/index.php/Chroot) (you need to be root for executing this): - - jujube -r +- As root - Allow to have fully root privileges inside JuJube environment using [arch-chroot](https://wiki.archlinux.org/index.php/Chroot) (you need to be root for executing this): ```jujube -r``` If the JuJube image has not been downloaded yet, the script will download the JuJube image and will place it to the default directory ~/.jujube. @@ -46,12 +41,17 @@ If you are new on Archlinux and you are not familiar with *pacman* package manag visit the [pacman rosetta page](https://wiki.archlinux.org/index.php/Pacman_Rosetta). Installation ------------- +============ +JuJube can works on GNU/Linux OS with kernel version greater or equal +2.6.0 (JuJube was not tested on kernel versions older than this) on 64 bit, 32 bit and ARM architectures. + +## Method one (Recommended) ## Just clone the JuJube repo somewhere (for example in ~/jujube): git clone git://github.com/fsquillace/jujube ~/jujube export PATH=~/jujube/bin:$PATH +## Method two ## Alternatively, another installation method would be to directly download the JuJube image and place it to the default directory ~/.jujube: ARCH= @@ -59,19 +59,31 @@ Alternatively, another installation method would be to directly download the JuJ curl https://dl.dropboxusercontent.com/u/42449030/jujube/jujube-${ARCH}.tar.gz | tar -xz -C ~/.jujube export PATH=~/.jujube/opt/jujube/bin:$PATH -JuJube can works on GNU/Linux OS with kernel version greater or equal -2.6.0 (JuJube was not tested on kernel versions older than this) on 64 bit, 32 bit and ARM architectures. +Dependencies +============ +JuJube comes with a very short list of dependencies in order to be installed in most +of GNU/Linux distributions. The needed executables in the host OS are: + +- bash +- wget or curl +- tar +- mkdir +- ln +- chown (for root access only) + +The minimum recommended linux kernel is 2.6.0+ Advanced usage --------------- -### Build image ### +============ + +## Build image ## You can build a new JuJube image from scratch by running the following command: jujube -b [-n] The script will create a directory containing all the essentials files in order to make JuJube working properly (such as pacman, yaourt, arch-chroot and proot). -The option `-n` will skip the final validation tests if they are not needed. +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 with arch-install-scripts, package-query, git and the base-devel packages installed. To change the build directory just use the *JUJUBE_TEMPDIR* (by default /tmp). @@ -81,9 +93,10 @@ After creating the image jujube-x86\_64.tar.gz you can install it by running: jujube -i jujube-x86_64.tar.gz Related wiki page: + - [How to build a JuJube image using QEMU](https://github.com/fsquillace/jujube/wiki/How-to-build-a-JuJube-image-using-QEMU) -### Bind directories ### +## Bind directories ## To bind a host directory to a guest location, you can use proot arguments: jujube -p "-b /mnt/mydata:/home/user/mydata" @@ -92,11 +105,11 @@ Check out the proot options with: jujube -p "--help" -###Automatic fallback to classic chroot### +##Automatic fallback to classic chroot## Since the [arch-chroot](https://wiki.archlinux.org/index.php/Chroot) may not work on some distros, JuJube automatically tries to fallback to the classic chroot. -### JuJube as a container ### +## JuJube as a container ## Although JuJube has not been designed to be a complete container, it is even possible to virtualize the process tree thanks to the [systemd container](https://wiki.archlinux.org/index.php/Systemd-nspawn). The JuJube containter allows to run services inside the container that can be @@ -109,107 +122,92 @@ To boot a JuJube container: sudo systemd-nspawn -bD ~/.jujube Related wiki page: + - [How to run jujube as a container](https://github.com/fsquillace/jujube/wiki/How-to-run-JuJube-as-a-container) -Dependencies ------------- -JuJube comes with a very short list of dependencies in order to be installed in most -of GNU/Linux distributions. The needed executables in the host OS are: -- bash -- wget or curl -- tar -- mkdir -- ln -- chown (for root access only) - -The minimum recommended linux kernel is 2.6.0+ - Troubleshooting ---------------- +=============== -###Cannot use AUR repository### -- **Q**: Why do I get the following error when I try to install a package with yaourt? -``` -Cannot find the gzip binary required for compressing man and info pages. -``` -- **A**: JuJube comes with a very basic number of packages. -In order to install packages using yaourt you may need to install the package group *base-devel* +##Cannot use AUR repository## + +> **Q**: Why do I get the following error when I try to install a package with yaourt? + + Cannot find the gzip binary required for compressing man and info pages. + +> **A**: JuJube comes with a very basic number of packages. +In order to install packages using yaourt you may need to install the package group **base-devel** that contains all the essential packages for compiling source code (such as gcc, make, patch, etc): -``` pacman -S base-devel -``` -###Kernel too old### -- **Q**: Why do I get the error: "FATAL: kernel too old"? -- **A**: This is because the executable from the precompiled package cannot +##Kernel too old## + +> **Q**: Why do I get the error: "FATAL: kernel too old"? + +> **A**: This is because the executable from the precompiled package cannot properly run if the kernel is old. JuJube contains two different PRoot binaries, and one of them is highly compatible with old linux kernel versions. JuJube will detect which PRoot binary need to be executed but you may need to specify the PRoot *-k* option if the guest rootfs requires a newer kernel version: -``` + jujube -p "-k 3.10" -``` In order to check if an executable inside JuJube environment can be compatible with the kernel of the host OS just use the *file* command, for instance: -``` file ~/.jujube/usr/bin/bash ELF 64-bit LSB executable, x86-64, version 1 (SYSV), dynamically linked (uses shared libs), for GNU/Linux 2.6.32, BuildID[sha1]=ec37e49e7188ff4030052783e61b859113e18ca6, stripped -``` From the output you can see what is the minimum recommended Linux kernel version. -###SUID permissions### -- **Q**: Why I do not have permissions for ping? -``` +##SUID permissions## +> **Q**: Why I do not have permissions for ping? + ping www.google.com ping: icmp open socket: Operation not permitted -``` -- **A**: The ping command uses *suid* permissions that allow to execute the command using +> **A**: The ping command uses *suid* permissions that allow to execute the command using root 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 that have *suid* permission, you can list the commands from your JuJube environment with the following command: -``` + find /usr/bin -perm +4000 -``` -###No characters are visible on a graphic application### -- **Q**: Why I do not see any characters in the application I have installed? +##No characters are visible on a graphic application## -- **A**: This is probably because there are no +> **Q**: Why I do not see any characters in the application I have installed? + +> **A**: This is probably because there are no [fonts](https://wiki.archlinux.org/index.php/Font_Configuration) installed in the system. To quick fix this, you can just install a fonts package: -``` - pacman -S gnu-free-fonts -``` -###Differences between filesystem and package ownership### -- **Q**: Why do I get warning when I install a package using root privileges? -``` + pacman -S gnu-free-fonts + +##Differences between filesystem and package ownership## + +> **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. +> **A**: In these cases the package installation went smoothly anyway. This should happen every time you install package with root privileges since JuJube will try to preserve the JuJube environment by assigning ownership of the files to the real user. -###No servers configured for repository### -- **Q**: Why I cannot install packages? -``` +##No servers configured for repository## + +> **Q**: Why I cannot install packages? + pacman -S lsof Packages (1): lsof-4.88-2 @@ -220,17 +218,20 @@ of the files to the real user. error: no servers configured for repository: community error: 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: -``` +> **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 -``` + +More documentation +================== +There are additional tutorials in the +[JuJube wiki page](https://github.com/fsquillace/jujube/wiki). License -------- +======= Copyright (c) 2012-2015 This program is free software; you can redistribute it and/or modify it @@ -247,15 +248,15 @@ You should have received a copy of the GNU General Public License along with this program. If not, see . Author ------- +====== Filippo Squillace WWW ---- +=== https://github.com/fsquillace/jujube Last words ---------- +========== Quote of the [lotus](http://en.wikipedia.org/wiki/Ziziphus_lotus) (a selvatic jujube plant) > Per nove infausti dì sul mar pescoso