Information about the Kicksecure Linux Installer for Testers and Developers. User documentation for the Installer can be found on the Kicksecure for Linux download or VirtualBox/Installer page

Design[edit]

There are several different options available for installing VirtualBox:

A) Manually follow upstream instructions.
B) Manually follow derivative instructions. (Documented for some distributions here.)
C) Use an installer. (Such as this installer.)
D) Install simplified by a derivative (such as Kicksecure) using APT. In Kicksecure, backports/fasttrack is enabled by default, and kernel headers are installed by default, making the installation of VirtualBox simpler. The primary command is simplified to sudo apt install --no-install-recommends virtualbox-qt.
E) Install simplified from a third-party repository.

Regarding option E), there are at least two sub-options:

1) We could have forked the VirtualBox package and made minor modifications where upstream (Debian, Oracle) decisions impact usability. All missing dependencies, such as kernel headers, could be added to the package. For Debian, adding kernel headers requires a one-line change to the debian/control file, specifically Depends: linux-headers-amd64. This is more challenging for Ubuntu-based systems, where the name is linux-headers-generic.
2) Ship the installer in a Debian package. (This has actually been done; dist-installer-cli is part of the usability-misc package.) This is not the main documented method. Adding a repository, installing the package, and running the installer necessitates multiple manual steps by the user. By creating a downloadable installer, we were able to reduce the process to only two command-line commands. This was also easier to develop than option 1) since there's no need to host multiple repositories for various distributions, such as one for Debian-based, Ubuntu-based, and one for Fedora-based systems.

Development Todo[edit]

Soon[edit]

Priority[edit]

Misc[edit]

Future[edit]

signed version numbers instead of querying API
- no need to distrust the source if we are verifying its signature.
- the API is for HTTP (curl) not for rsync.
#Graphical Installer

Recently rejected[edit]

Recently rejected ideas are here, soon to be excluded.

Uninstall Guests, Hypervisor

--uninstall-vms --uninstall-gateway-xfce --uninstall-workstation-xfce --uninstall-virtualizer --uninstall-all

Testers Wanted[edit]

Here are some ideas for testing.

Do not use --no-show-errors and --allow-errors when debugging, unless you explicitly want that behavior.

Use --testers to download testers version and --dev to download empty Whonix-Xfce for VirtualBox.

If you want to try to find bugs, mix the options, miss some, add some, check the result, try other options not mentioned here.

These are raw tests and you still should read the script logs.

Common options and testing if option parsing is working:

dist-installer-cli --non-interactive --no-boot --dry-run --guest kicksecure --hypervisor=kvm -i cli -u=17.0.3.4 --onion --socks-proxy 127.0.0.1:9050 -l info

Check that the correct version is being printed and only it is being printed, nothing more:

dist-installer-cli --version

Download Kicksecure-CLI for KVM: dist-installer-cli -k -n -g kicksecure -i cli -m kvm --mirror 1

Download whonix from specified mirror and do signature verification but do not import anything:

dist-installer-cli -k -n -g whonix --mirror 1 --no-import

Redownload whonix and import only the gateway (check if files were redownloaded/synced and if only gateway was imported):

dist-installer-cli -k -n -g whonix --import-only gateway --redownload

Reimport only the gateway (check that only the gateway was imported and it overwrote only the previous gateway):

dist-installer-cli -k -n -g whonix --import-only gateway --reimport --destroy-existing-guest

Import only the workstation (check that only the workstation was imported):

dist-installer-cli -k -n -g whonix --import-only workstation

Developer Information[edit]

How to add support for a different host operating system?[edit]

This can only be done if you are a developer and is committed to test and report about the wanted operating system. This is because the Kicksecure Team does not have all resources to test under all umbrellas.

If you want to add support, please open an issue in the forum mentioning your interest.

You will face the following challenges:

Add commands that your package manager uses to
- test if packages were installed
- install command
- update command

Handle programs that changed the upstream name to another name, such as Debian's "signify-openbsd", should be called universally simply "signify".

Handle installing the hypervisor from the package manager itself, even if the package is not present in the main branch, but on Debian's "fasttrack" for example.

Notes[edit]

Exit Codes[edit]

Exit code 0 does not guarantee that the script did what was expected to be done, it just means it didn't find any errors along the way. Let's take import-only for example, it may not fail, but did it actually import only the specified VM? If combined with reimport, did it reimport only the specified VM?

Naming[edit]

General[edit]

dist-installer-gui
dist-installer-cli

VirtualBox Installer[edit]

virtualbox-installer-gui
virtualbox-installer-cli

Kicksecure[edit]

kicksecure-xfce-installer-gui
kicksecure-cli-installer-gui
kicksecure-xfce-installer-cli
kicksecure-cli-installer-cli

Whonix[edit]

whonix-cli-installer-gui
whonix-xfce-installer-gui
whonix-cli-installer-cli
whonix-xfce-installer-cli

Graphical Installer[edit]

toolkit ideas[edit]

makeself - in Debian
AppImage - build dependencies not in Debian - https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=854902
Nuitka - Python compiler - only in Debian unstable, will be in testing, long term candidate
https://packages.debian.org/bookworm/pex - Python compiler
https://github.com/icculus/mojosetup - not in Debian
freepascal

requirements[edit]

all build dependencies available from packages.debian.org (but this can be discussed if impossible to do so)
standalone installer, this means:
- self-contained
- no dependency installation such as "sudo apt install zenity" required by the user
compatible with the most popular stable Linux distributions such as Debian, Ubuntu and Fedora
- no need to be compatible with oldstable, old Linux distributions
do not re-invent dist-installer-cli
a GUI wrapper around dist-installer-cli (CLI)

info[edit]

implementation details[edit]

look at param(0) to find out the script's own name
- Script Name Verification: The installer checks for valid script names,
  - dist-installer-cli-gui
  - virtualbox-installer
  - kicksecure-cli-installer-cli: --guest=kicksecure --interface=cli
  - kicksecure-xfce-installer-cli: --guest=kicksecure --interface=xfce
  - whonix-cli-installer-cli: --guest=kicksecure=whonix --interface=cli
  - whonix-xfce-installer-cli: --guest=kicksecure=whonix --interface=xfce
show a logo (similar to Whonix Windows Installer)
- Kicksecure
- Whonix
- VirtualBox Installer (placeholder, logo does not exist yet)
parse man page, if possible
- or parse --help
- in case of man page or --help issues: Fix or discuss the underlying issues at the root cause of the issue. Do not add workarounds to the installer GUI. Not need for workarounds as man page / --help can be adjusted as needed as long as that makes sense.
- man page and/or --help can be modified for a machine (freepascal) readable format
- Why? To avoid installer GUI "learning" all the same options.
- use long option names such as --log-level=info instead of -l
- Parse what?
  - option name such as
  - option type:
    - checkbox
      - example: --onion
    - radio option
      - example: --log-level=debug, info, notice (default), warn, error
    - free text option
      - example: --socks-proxy=<proxy>
  - parse help text for option
if dist-installer-cli-gui is given a command line option such as dist-installer-cli-gui --dev then preselect that option in the GUI and pass it on to dist-installer-cli.
pages:
- page 1: welcome screen -> next button
- page 2: select options -> next button
  - page 2: also has a drop-down menu with advanced options
- page 3: show the CLI output of dist-installer-cli
  - show either a success icon and success message or a failure icon and failure message, depending on the exit code of installer dist-installer-cli

Root[edit]

The installer GUI should be executed as a normal user, not as root. This is in adherence to the native Wayland protocol, which disallows the execution of GUI applications as root. Any attempts to circumvent this restriction result in the activation of the Xwayland compatibility layer, a scenario best avoided for future-proofing.

It might be prudent for the installer to invoke the sudo command directly. This seems plausible.

Should sudo be absent, an error message should be displayed.

sudo is unavailable, aborting the installer. Consider utilizing the CLI version of this installer, which accommodates sudo, su, and doas. Refer to: https://www.kicksecure.com/wiki/Dev/Linux_Installer#sudo

If feasible, initiate a terminal window within the GUI and execute the script below.

#!/bin/bash

## Copyright (C) 2023 - 2023 ENCRYPTED SUPPORT LP <adrelanos@whonix.org>
## See the file COPYING for copying conditions.

## This script assists in prompting sudo authorization for the user.
## It ensures sudo credential caching is enabled on the system.
## This script assumes that dist-installer-gui has already
## verified the installation of sudo.
## To avoid redundancy, code from dist-installer-cli is utilized.

## NOTE: This script may exit with a non-zero exit code upon failure.

#set -x
set -e

true "$0: START"

## TODO: Modify path
source usr/bin/dist-installer-cli

set_default
get_su_cmd

if [ "$credential_caching_status" != "yes" ]; then
  log error "Sudo credential caching is essential for this graphical installer."
  exit 1
fi

true "$0: TERMINATED: SUCCESS."

Upon successful sudo authorization via this (child) script, the GUI (parent) should automatically inherit the authorization status, courtesy of sudo's default credential caching mechanism.

For users who have configured sudo to employ alternative authentication methods, such as fingerprint recognition, leveraging sudo directly for root access should ensure compatibility.

If the sudo authorization script fails (by exiting with a non-zero exit code) the dist-installer-gui should show an error message.

sudo authorization failed. You can always re-run this installer. Refer to: https://www.kicksecure.com/wiki/Dev/Linux_Installer#sudo

Forum Discussion[edit]

Forum discussion

Debug Log[edit]

Debug logs are located in the directory:

~/dist-installer-cli-download/logs/

Within this directory, you might find numerous sub-folders, each represented by a unique number. These numbers act as counters, indicating how many times the installer has been initiated by the user. Typically, the log with the highest number (i.e., the most recent one) will be of primary interest.

When the installer is in operation, it will produce an output containing a line akin to:

xfce-installer-cli: [NOTICE]: Saving debug log to: '/home/user/dist-installer-cli-download/logs/115/debug.log'

In the aforementioned example, the number 115 is showcased. Do note, this number will vary with each installation.

Within these numbered directories, you can expect to find the following three files:

debug.log
user.log
A copy of the installer executed during that particular session.

Kicksecure^™ Linux Installer - Design Documentation

Contents

Design[edit]

Development Todo[edit]

Soon[edit]

Priority[edit]

Misc[edit]

Future[edit]

Recently rejected[edit]

Testers Wanted[edit]

Developer Information[edit]

How to add support for a different host operating system?[edit]

Notes[edit]

Exit Codes[edit]

Naming[edit]

General[edit]

VirtualBox Installer[edit]

Kicksecure[edit]

Whonix[edit]

Graphical Installer[edit]

toolkit ideas[edit]

requirements[edit]

info[edit]

implementation details[edit]

Root[edit]

Forum Discussion[edit]

Debug Log[edit]

See Also[edit]

Navigation menu

Kicksecure™ Linux Installer - Design Documentation

Design[edit]

Development Todo[edit]

Soon[edit]

Priority[edit]

Misc[edit]

Future[edit]

Recently rejected[edit]

Testers Wanted[edit]

Developer Information[edit]

How to add support for a different host operating system?[edit]

Notes[edit]

Exit Codes[edit]

Naming[edit]

General[edit]

VirtualBox Installer[edit]

Kicksecure[edit]

Whonix[edit]

Graphical Installer[edit]

toolkit ideas[edit]

requirements[edit]

info[edit]

implementation details[edit]

Root[edit]

Forum Discussion[edit]

Debug Log[edit]

See Also[edit]

Navigation menu

Kicksecure^™ Linux Installer - Design Documentation