Kicksecure Linux Installer - Design Documentation
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, specificallyDepends: linux-headers-amd64
. This is more challenging for Ubuntu-based systems, where the name islinux-headers-generic
. - 2) Ship the installer in a Debian package. (This has actually been done;
dist-installer-cli
is part of theusability-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]
- https://github.com/Kicksecure/usability-misc/blob/master/usr/bin/dist-installer-cli
- https://github.com/Kicksecure/usability-misc/blob/master/man/dist-installer-cli.1.ronn
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=clikicksecure-xfce-installer-cli
: --guest=kicksecure --interface=xfcewhonix-cli-installer-cli
: --guest=kicksecure=whonix --interface=cliwhonix-xfce-installer-cli
: --guest=kicksecure=whonix --interface=xfce
- Script Name Verification: The installer checks for valid script names,
- 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
- example:
- radio option
- example:
--log-level=debug
,info
,notice
(default),warn
,error
- example:
- free text option
- example:
--socks-proxy=<proxy>
- example:
- checkbox
- parse help text for option
- or parse
- 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 todist-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
- show either a success icon and success message or a failure icon and failure message, depending on the exit code of installer
Forum Discussion[edit]
See Also[edit]
Unfinished: This wiki is a work in progress. Please do not report broken links until this notice is removed, use Search Engines First and contribute improving this wiki.

We believe security software like Kicksecure needs to remain open source and independent. Would you help sustain and grow the project? Learn more about our 10 year success story and maybe DONATE!