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
appiamge - 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

Forum Discussion[edit]

Forum discussion

Kicksecure Linux Installer - Design Documentation

Contents