Kicksecure Linux Installer - Design Documentation

From Kicksecure
< Dev
Revision as of 18:35, 17 August 2023 by Grass-admin (talk | contribs) (move page from whonix to kicksecure)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

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

Testers Wanted

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:

Click = Copy Copied to clipboard! installer-dist --non-interactive --no-boot --dry-run --guest kicksecure --hypervisor=kvm -i cli -u=16.0.9.0 --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:

Click = Copy Copied to clipboard! installer-dist --version

Download Kicksecure-CLI for KVM: Click = Copy Copied to clipboard! installer-dist -k -n -g kicksecure -i cli -m kvm --mirror 1

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

Click = Copy Copied to clipboard! installer-dist -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):

Click = Copy Copied to clipboard! installer-dist -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):

Click = Copy Copied to clipboard! installer-dist -k -n -g whonix --import-only gateway --reimport --destroy-existing-guest

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

Click = Copy Copied to clipboard! installer-dist -k -n -g whonix --import-only workstation

Developer Information

How to add support for a different host operating system?

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

Exit Codes

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?

Development Todo

Soon

misc

  • add support for Oracle Vbox repo. Currently there is no need, maybe in the future with outdated packages on the main distributions.
    • one of the problems is that the vbox key needs to be contained in the installer, while we are using signify to verify the images because it is better and the key is only two lines long.
    • https://www.kicksecure.com/wiki/VirtualBox/Other_Versions#Install_from_VirtualBox.org_Repositoryarchive.org iconarchive.today icon
      • use extrepo? or manual method? extrepo might not support tor+?
        • problem with extrepo is as of current stable Debian 11 (Bullseye), extrepo-data is only available from backports and the problem with manual method is gpg.
    • virtualbox package name auto detection: detect version number virtualbox-6.1 versus virtualbox-7.0 or maybe in virtualbox-7.1. Probably virtualbox-(3 characters)
    • after adding the repository and after updating the package lists (apt-get update) maybe apt-cache can be used
      • apt-cache search --names-only --quiet virtualbox-
      • apt-cache supports regex (but could also use awk, grep)
  • header package name auto detection: try linux-headers-generic first, then fall back to linux-headers-amd64, then fall back to linux-headers-$(uname -r)
    • check availability using apt-cache?
      • Click = Copy Copied to clipboard! apt-cache search --names-only --quiet linux-headers-generic\$
      • Click = Copy Copied to clipboard! apt-cache search --names-only --quiet linux-headers-amd64\$
      • Click = Copy Copied to clipboard! search_string="linux-headers-$(uname -r)" ; apt-cache search --names-only --quiet "$search_string\$"

Future

  • 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
    • examples?

Done

  • CI
    • abort CI run if a script other than installer-dist was modified to safe CI minutes?
  • os support
    • debian stable, other debian releases are not compatible with virtualbox.
    • supports debian derivatives such as kicksecure and ubuntu derivatives such as mint.
  • installer-dist could contain a fixed, magic string such as "##commit-hash-replace-me##", use str_replace to search for that string and replace with the commit hash.
  • --mirror
    • indexed to make it easier to choose by number, not writing whole domain.
  • backup script and its logs to a folder in the target with the run timestamp.
    • mention in the logs where it is being saved to.
    • Troubles: not executing trap when exiting, mixing/joining stdout and stderr output, not printing to both stdout and the file correctly.
    • exit trap works but mixes stdout and stderr: main 2>&1 | tee "${log_file}"
    • leaves stdout and stderr separate but trap does not work: exec > >(tee -a "${log_file}"); exec 2> >(tee -a "${log_file}" >&2); main
  • --import-only gateway|workstation
    • didn't find a way to do this with vbox gui or cli. It seems that to import one virtual system, licenses of both virtual systems needs to be accepted and both will be imported.
    • if not accepting both licenses, this happens: VBoxManage: error: Cannot import until the license agreement listed above is accepted.
    • https://forums.virtualbox.org/viewtopic.php?f=1&t=107965archive.org iconarchive.today icon
    • modify vmname and delete it later.
  • if vms were already imported, ask user if they want to start the vms.
  • log important commands.
  • change default download directory to $HOME/installer-dist-download.
  • set default license answer to agree.
    • can't do that on whiptail because of its limitations. When text is too long and scrolltext is needed, the yesno box does not display a default item. (note: --default-item is for items in the box to be selected as menu for example, not for buttons).
  • if vm was imported
    • start (default) (safe)
    • force-download (difficult to understand purpose for users)
    • factory-reset (can lead to data loss)
  • man page
  • bash completion
  • zsh completion
  • changing default features (download Whonix vs KS) depending on the name of the script
  • download from clearnet by default, support command line parameter to download from onion instead
  • check if fasttrack repo is already enabled clearnet/onion
  • wrap all into a function (guard bash pipe against server partial content transfer)
  • call specific functions only such as get_version for testing
    • dry-run mode was implemented instead because some functions depends on many others being called before.
  • check architecture - anything other than amd64 is unsupported by VirtualBox
    • check uname --machine is x86_64
    • this might be different later for KVM
    • check early
    • notify in textual output early
    • remind that this is a missing step at the end of the instillation process
      • do not offer to start VirtualBox because of this
  • check if enough disk space is available
  • use API to get latest stable version number
    • command line switch to download testers version instead
    • command line switch or env var to select arbitrary version
  • Multi distribution support:
    • Debian bullseye
    • Ubuntu 22.04
    • Kicksecure 16
  • Debian:
    • install fasttrack signing key
    • add fasttrack repository
  • Ubuntu:
    • check it's Ubuntu 22.04 or above - warn/abort for earlier versions
  • Kicksecure:
    • Installation is simpler than on Debian. This is already documented on VirtualBox
  • install what?
    • Whonix for VirtualBox
    • potentially later to be extended to download Kicksecure
      • therefore the download location URL needs to be a variable
  • download progress meter needed
  • source code design optimization
    • Split into separate functions or scripts that do checks versus those that perform tasks.
      • What are tasks? For example, updating the package lists, install VirtualBox, download Whonix, import Whonix VMs.
      • Maybe good if these scripts can be tested standalone to make these easier to maintain?
      • Perhaps some shared command line parsing / variables are needed?
  • torify connections without changing user configuration
    • do not spawn a daemon, this bypass the main daemon bridges etc.
    • do not edit user configuration, this is very hard to do right and to do clean up later
    • give command line option to use a SOCKS proxy so user specify their own, if none specified, user tor variable TOR_SOCKS_HOST (default: 127.0.0.1) and TOR_SOCKS_PORT. If the TOR_SOCKS_PORT is not set at all, default to TBB 9150 and then system tor 9050.
  • Accept legal texts vs --no-interactive
  • privileged user
    • run as user and makes inform about having long timeouts for the user password, because logged in as root is not a good option and the script won't know to which user add to the group vboxusers.
    • demand to not run as root
    • choose sudo, doas, su.
  • abort if the VMs already exist?
    • the system updates with apt, the VM file name version could still be using a previous version. Abort and inform.
    • if the VM is deleted, user could lose user data.
  • idempotent - possible to re-run the installer multiple times without breaking things
  • NO_COLOR https://no-color.org/archive.org iconarchive.today icon

Logging

  • Needs to keep updating the user, inform approximately how long things will take. "This will take a moment." "This will take a while." This is needed to reassure the user that the installer isn't frozen, which then results to the user closing the installer which then results in the installer being run multiple times which shouldn't but could cause issues.
    • log function implemented to be verbose about the running commands.

Click = Copy Copied to clipboard! installer-dist -l info 

installer-dist: [NOTICE]: Testing internet connection...
verify depth is 4

Please show the command that is used to test internet connection. (Since using debug level info.) 

installer-dist: [INFO]: Acquiring guest version from API.
installer-dist: [INFO]: API host: https://www.whonix.org/w/index.php?title=Template:VersionNew&stable=0&action=raw

Same as above. 

installer-dist: [NOTICE]: Downloading rsync://mirrors.dotsrc.org/whonix/ova/16.0.9.0/Whonix-Xfce-16.0.9.0.ova.
opening connection using: /usr/bin/rsync-ssl --HELPER mirrors.dotsrc.org rsync --server --daemon .  (7 args)
verify depth is 4
sending daemon args: --server --sender -vvze.LsfxCIvu --timeout=600 . whonix/ova/16.0.9.0/Whonix-Xfce-16.0.9.0.ova  (6 args)
delta-transmission enabled

Same as above.

Virtualization

  • check if virtualization is enabled in BIOS


apt-get install debugging

Users having local issues (not caused by installer-dist) with their APT package management system could be quite common. (Such as when APT / dpkg was previously interrupted during a dist-upgrade or a package installation.) In these cases no packages can be installed. This includes the inability to install VirtualBox.

To find out if that is happening, the installer could run a few commands as sanity test. Some pseudo code inspired by systemcheck: 


   ## dpkg --audit does not exit with a non-zero exit code if something is wrong.
   ## dpkg --audit does not return anything, if everything is fine.
   ## Therefore we see if dpkg has to say something, and if yes, the system is
   ## broken and we abort.
   dpkg_audit_output="$(dpkg --audit 2>&1)" || true

   if [ "$dpkg_audit_output" = "" ]; then
      ## OK
   else
      ## issue. Show output of dpkg_audit_output and link to wiki.
   fi


dropped due to outdated installer version

apt-get update debugging

Note: this is not a problem with apt-get update, it was a problem with the script itself and its logs no being correctly printed.

In https://forums.whonix.org/t/can-i-report-a-bug-here/16142/2archive.org iconarchive.today icon a user reported a log containing: 

709 log_run “root_cmd ${pkg_mngr_update}”

1) That is not verbose enough. Would be better if the log could be seen.

2) Users having local issues (not caused by installer-dist) with their APT package management system could be quite common. (Duplicate sources, some broken repositories.) Therefore installer-dist should advice the user so the user doesn't have to ask in the forums.

Advice could either be built into installer-dist or probably better, a link to a wiki page? If a wiki page, then Patrick could

dpkg/apt log debugging

Note: apt already warns that another process is holding the lock and tells the user to wait. 

   ## If a package manager is running:
   ## sudo --non-interactive fuser /var/lib/dpkg/lock /var/cache/apt/archives/lock ; echo $?
   ## /var/lib/dpkg/lock:  15601
   ## /var/cache/apt/archives/lock: 15601
   ## 0
   ##
   ## If no package manager is running:
   ## sudo --non-interactive fuser /var/lib/dpkg/lock /var/cache/apt/archives/lock ; echo $?
   ## 1
   if sudo --non-interactive fuser /var/lib/dpkg/lock /var/cache/apt/archives/lock ; then
      echo "A package manager is already running. Cannot proceed. See: link to wiki"
   fi

Naming

General

  • dist-installer-gui
  • dist-installer-cli

Kicksecure

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

Whonix

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

Graphical Installer

toolkit ideas

requirements

  • 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 installer-dist
  • a GUI wrapper around installer-dist (CLI)

info

implementation details

  • look at param(0) to find out the script's own name
    • Script Name Verification: The installer checks for valid script names,
      • installer-dist-gui
      • virtualbox-installerOnion Logo
      • kicksecure-installer-cli --guest=kicksecure --interface=cli
      • kicksecure-installer-xfce --guest=kicksecure --interface=xfce
      • whonix-installer-cli --guest=kicksecure=whonix --interface=cli
      • whonix-installer-xfce --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 installer-dist-gui is given a command line option such as installer-dist-gui --dev then preselect that option in the GUI and pass it on to installer-dist.
  • 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 installer-dist
      • show either a success icon and success message or a failure icon and failure message, depending on the exit code of installer installer-dist

Forum Discussion

Forum discussionarchive.org iconarchive.today icon

See Also

Your support makes
all the difference!

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 12 year success story and maybe DONATE!

Retrieved from "https://www.kicksecure.com/w/index.php?title=Dev/Linux_Installer&oldid=75908"