{{Header}} {{hide_all_banners}} {{Title|
title=Install {{project_name_long}} inside a folder (chroot)
}}
[[image:Download-chroot.jpg|thumb]]
{{#seo:
|description=You can install {{project_name_short}} on top of your existing Debian (based) Linux installation inside a chroot (change root).
|image=Download-chroot.jpg
}}
{{intro|
You can install [[About|{{project_name_short}}]] on top of your existing Debian (based) Linux installation inside a [[chroot]].
}}
= Introduction =
'''Understanding the Basics of Creating and Using a Chroot Environment'''

Creating and using a chroot is like building a small, isolated Linux system within your main system. It's a powerful tool for various purposes, from development to testing. While the concept might seem overwhelming at first, it boils down to a few key commands and a basic understanding of Linux file systems.

In the world of Linux, mastering the creation and use of a chroot (change root) environment is a valuable skill. This process involves two fundamental steps: creating the chroot and then operating within it.

Before we can discuss the chroot (change root), we first need to define what the root directory is. In Linux, the root directory path symbolized only by a single <code>/</code> (forward slash). See also {{CodeSelect|code=ls /|inline=true}}. It contains other directories you might already know such as <code>/etc</code>, <code>/usr</code>, <code>/lib</code>, <code>/var</code>, and so forth.

'''Creating the Chroot Environment'''

The chroot environment is essentially a miniature version of a Linux system within your existing system.
 
To create this environment, you can use tools like ''debootstrap'' or ''mmdebstrap''. These tools download a Linux distribution (like Debian or others from different repositories such as Kicksecure) and establish a root file system in a designated folder on your hard drive. For instance, you might create a chroot folder named <code>~/kicksecure-xfce-chroot</code>. That folder would then contain same essential directories, <code>/etc</code>, <code>/usr</code>, and so forth. Here's an example how that folder structure would look like.

* <code>~/kicksecure-xfce-chroot/etc</code>
* <code>~/kicksecure-xfce-chroot/usr</code>
* <code>~/kicksecure-xfce-chroot/lib</code>
* etc.

This folder structe gets created by the chroot creation tool. There's no need for the user to fully understand the folder structure or process. The process is straightforward, typically requiring just a single command line instruction.

'''Using the Chroot Environment'''

Once the chroot folder has been set up, you can start working inside it using commands like ''chroot'' or ''systemd-nspawn''.

An example of entering this environment would be: <code>sudo chroot ~/kicksecure-xfce-chroot zsh</code>. This command changes the root from the main <code>/</code> to <code>~/kicksecure-xfce-chroot</code> and starts the Z shell (zsh) in this new context. But don't worry. This does not change the root for your real Linux installation. It only changes the root for the terminal emulator which you are currently using. The rest of your system remains unaffected by this.

You could also use other shells such as <code>bash</code> or applications as needed.

It’s worth noting that more advanced setups might involve emulators like QEMU for a fully emulated operating system, but this would require additional steps like installing a kernel in the chroot.

= chroot Creation =
{{Disclaimer}}
== Qubes Notes ==
Only users of Qubes need to consider these notes in this chapter.

Users that don't use Qubes or don't know what Qubes is should skip this chapter.

TODO: elaborate

* nosuid / nodev can cause issues?
* default private image size (/home folder) is too small for {{project_name_short}} Xfce

== Install Required Tools ==
<ref>
* <code>apt-transport-https</code> is required for some older Debian based Linux distributions that have not integrated https support into APT yet. If not available in your distribution, can be safely ignored.
* <code>apt-transport-tor</code> is required because [https://github.com/{{project_name_short}}/anon-apt-sources-list/blob/master/etc/apt/sources.list.d/debian.list /etc/apt/sources.list.d/debian.list] is using <code>tor+https</code>. Otherwise we would see the following error.
<pre>
I: cleaning package lists and apt cache...
Reading package lists...
E: The method driver /usr/lib/apt/methods/tor+https could not be found.
E: The method driver /usr/lib/apt/methods/tor+https could not be found.
E: The method driver /usr/lib/apt/methods/tor+https could not be found.
E: Failed to fetch tor+https://deb.debian.org/debian-security/dists/buster/updates/InRelease
E: Failed to fetch tor+https://deb.debian.org/debian/dists/buster/InRelease
E: Failed to fetch tor+https://deb.kicksecure.com/dists/buster-developers/InRelease
E: Some index files failed to download. They have been ignored, or old ones used instead.
E: apt --option Dir::Etc::SourceList=/dev/null update -oAPT::Status-Fd=<$fd> -oDpkg::Use-Pty=false failed
</pre>
* <code>tor</code> is required so <code>apt-transport-tor</code> can use Tor. Otherwise we would see the following error.
<pre>
I: cleaning package lists and apt cache...
Err:1 tor+https://deb.debian.org/debian-security buster/updates InRelease
  Could not connect to 127.0.0.1:9050 (127.0.0.1). - connect (111: Connection refused)
Err:2 tor+https://deb.debian.org/debian buster InRelease
  Unable to connect to 127.0.0.1:9050:
Err:3 tor+https://deb.kicksecure.com buster-developers InRelease
  Could not connect to 127.0.0.1:9050 (127.0.0.1). - connect (111: Connection refused)
Reading package lists...
W: Failed to fetch tor+https://deb.debian.org/debian-security/dists/buster/updates/InRelease  Could not connect to 127.0.0.1:9050 (127.0.0.1). - connect (111: Connection refused)
W: Failed to fetch tor+https://deb.debian.org/debian/dists/buster/InRelease  Unable to connect to 127.0.0.1:9050:
W: Failed to fetch tor+https://deb.kicksecure.com/dists/buster-developers/InRelease  Could not connect to 127.0.0.1:9050 (127.0.0.1). - connect (111: Connection refused)
W: Some index files failed to download. They have been ignored, or old ones used instead.
</pre>
* Actually package <code>apt-transport-tor</code> recommends package <code>tor</code> but listing it here anyhow for those using APT with parameter <code>--no-install-recommends</code>.
* <code>apt-transport-https</code> is suggested below to download the signing key.
</ref>

{{Install Package
|package=mmdebstrap apt-transport-https apt-transport-tor tor curl
}}

== Add Signing Key ==
{{Box|text=
It is required to add the signing key on the host because <code>mmdebstrap</code> will need it.

(Users of {{project_name_short}} and {{project_name_short}} could skip this step since the signing key is there by default.)

Key could be removed at the end. (Except {{project_name_short}} and {{project_name_short}} should not do this unless they upgrade from source code.)

{{W-APT-Repository-Key}}
}}

== Set Variables ==
File <code>/etc/hostname</code> must exist. <ref>
Fixed in <code>mmdebstrap</code> <code>0.5.0</code>. Quote [https://gitlab.mister-muffin.de/josch/mmdebstrap/src/branch/main/CHANGELOG.md changelog]:
<blockquote>
do not copy /etc/resolv.conf or /etc/hostname if the host system doesn't have them
</blockquote>
Therefore no longer required in Debian <code>bullseye</code>.
</ref>

{{CodeSelect|code=
sudo touch /etc/hostname
}}

== Set Variables ==
Note: You could also replace <code>kicksecure-xfce</code> with <code>kicksecure-cli</code>.

{{CodeSelect|code=
package=kicksecure-xfce
repo={{Stable project version based on Debian codename}}
path_to_chroot=~/kicksecure-xfce-chroot
path_to_temp_sources_list=~/temp-sources.list
}}

== APT Sources List ==
Create temporary APT sources list for <code>mmdebstrap</code>.

{{CodeSelect|code=
echo "
deb https://deb.debian.org/debian-security {{Stable project version based on Debian codename}}-security main contrib non-free
deb https://deb.debian.org/debian {{Stable project version based on Debian codename}} main contrib non-free
deb [signed-by=/usr/share/keyrings/derivative.asc] https://deb.{{project_clearnet}} $repo main contrib non-free
" > "$path_to_temp_sources_list"
}}

== APT Cache ==
<div class="toccolours mw-collapsible mw-collapsed">
<u>Optional.</u> If you are interested, please press Expand on the right side.
<div class="mw-collapsible-content">
This shouldn't be done unless you are behind a firewall since apt-cacher-ng will by default listen on all network interfaces.

{{Install Package
|package=apt-cacher-ng
}}

Set <code>apt_cacher_ng_maybe</code> variable. <ref>
No longer working.

{{CodeSelect|code=
apt_cacher_ng_maybe="--aptopt='Acquire::http { Proxy \"http://127.0.0.1:3142\"; }' --aptopt='Acquire::https { Proxy \"http://127.0.0.1:3142\"; }' --aptopt='Acquire::tor { Proxy \"http://127.0.0.1:3142\"; }'"
}}
</ref>

{{CodeSelect|code=
http_proxy=http://127.0.0.1:3142
}}

Create apt-cacher-ng https compatible sources.list file.

{{CodeSelect|code=
echo "
deb http://HTTPS///deb.debian.org/debian-security/ {{Stable project version based on Debian codename}}-security main contrib non-free
deb http://HTTPS///deb.debian.org/debian {{Stable project version based on Debian codename}} main contrib non-free
deb [signed-by=/usr/share/keyrings/derivative.asc] http://HTTPS///deb.kicksecure.com $repo main contrib non-free
" > "$path_to_temp_sources_list"
}}
</div>
</div>

== Run mmdebstrap ==
Run <code>mmdebstrap</code>. <ref>
* <code>debootstrap</code> cannot be used since it is a single-mirror Debian chroot creation tool. I.e. it cannot use multiple APT repositories at the same time. And {{project_name_short}} APT repository does not ships no packages available from packages.debian.org. Therefore using <code>mmdebstrap</code> which is a multi-mirror Debian chroot creation.
** If you cannot use <code>mmdebstrap</code> either (cross platform builds?), you could first create a Debian chroot using <code>debootstrap</code> (or anything) and then install a {{project_name_short}} meta package manually inside the chroot.
* Whonix: add <code>anon_shared_inst_tb=open</code>
</ref>

{{CodeSelect|code=
sudo \
   $apt_cacher_ng_maybe \
   SECURITY_MISC_INSTALL=force \
   DERIVATIVE_APT_REPOSITORY_OPTS=stable \
   mmdebstrap \
      --verbose \
      --variant=required \
      --include $package \
      $repo \
      "$path_to_chroot" \
      "$path_to_temp_sources_list"
}}

== Chroot Post Processing ==
Delete the chroot's temporary <code>/etc/apt/sources.list</code>. <ref>
During chroot build process the following files were already created.

* <code>/etc/apt/sources.list.d/debian.list</code>
* <code>/etc/apt/sources.list.d/derivative.list</code>
</ref>

{{CodeSelect|code=
sudo rm "$path_to_chroot/etc/apt/sources.list"
}}

{{CodeSelect|code=
sudo rm "$path_to_chroot/etc/apt/sources.list.d/0000temp-sources.list"
}}

== Host Cleanup ==

<div class="toccolours mw-collapsible mw-collapsed">
<u>Optional.</u> You can delete the signing key from the host.

If you are interested, please press Expand on the right side.
<div class="mw-collapsible-content">
This is only useful for users not using {{project_name_short}} as their host operating system.

Users of {{project_name_short}} must skip this.

{{CodeSelect|code=
sudo rm /etc/apt/trusted.gpg.d/derivative.gpg
}}
</div>
</div>

= Usage =
=== Simple Classic Chroot Method ===
{{CodeSelect|code=
sudo chroot ~/kicksecure-xfce-chroot zsh
}}

== systemd-nspawn Method ==
=== Install systemd-nspawn ===

{{CodeSelect|code=
sudo apt install systemd-container
}}

=== systemd-nspawn Simple Chroot ===
{{CodeSelect|code=
sudo systemd-nspawn -D ~/kicksecure-xfce-chroot
}}

=== systemd-nspawn Boot Chroot CLI Only ===
{{CodeSelect|code=
sudo systemd-nspawn -D ~/kicksecure-xfce-chroot /sbin/init
}}

==== Troubleshooting ====
===== sudo =====
{{CodeSelect|code=
sudo su
}}

If seeing this error when using "sudo su".

<pre>
sudo: effective uid is not 0, is /usr/bin/sudo on a file system with the 'nosuid' option set or an NFS file system without root privileges?
</pre>

* Qubes users:
** If using mounting home with nosuid.

{{CodeSelect|code=
sudo mount -o remount,suid /rw/home
}}

===== networking =====
systemd-networkd must be enabled on both, the host and inside the VM.

{{CodeSelect|code=
sudo systemctl enable systemd-networkd
}}

{{CodeSelect|code=
sudo systemctl start systemd-networkd
}}

=== systemd-nspawn Boot Chroot with GUI Support ===
This is unfinished. Unspecific to {{project_name_short}}. Could be resolved as per [[Self_Support_First_Policy|Self Support First Policy]].

{{CodeSelect|code=
xhost +local:
}}

{{CodeSelect|code=
sudo systemd-nspawn --setenv=DISPLAY=$DISPLAY -D ~/kicksecure-xfce-chroot /sbin/init
}}

=== Exit systemd-nspawn Chroot ===
{{systemd-nspawn-exit}}

=== Limitations of systemd-nspawn based Chroot ===
Despite these limitations, <code>systemd-nspawn</code> should probably preferred over classic <code>chroot</code>. Depends on what you are trying to accomplish.

* [[sdwdate]] (and [[Boot Clock Randomization]]) cannot work inside <code>systemd-nspawn</code>.
* Tor will fail to start inside <code>systemd-nspawn</code> <code>chroot</code> if Tor is already running on the host in default config (local listen post <code>9050</code>). But that shouldn't matter. The <code>systemd-nspawn</code> <code>chroot</code> will use the host's Tor in this case. <code>systemd-nspawn</code> has also option to run private networking but these have not been researched for {{project_name_short}} yet.

= Footnotes =
{{reflist|close=1}}
{{Footer}}
[[Category:Documentation]]