DIST-INSTALLER-CLI(1)

NAME
dist-installer-cli - download and import Whonix/Kicksecure VMs

SYNOPSIS
dist-installer-cli options

DESCRIPTION
dist-installer-cli is an installer that automates the download and import of Kicksecure and Whonix VMs. It supports interfaces CLI or LXQt, and allows users to choose their preferred hypervisor, such as KVM or VirtualBox.

OPTIONS
Options start with one or two dashes. Both long and short options that require arguments can be separated by either spaces or an equal sign.

If an option is specified multiple times, the last assignment takes precedence.

The guest and interface can also be set by renaming the script following the format guest-interface-installer.

-g, --guest=guest

        Set the guest operating system. Options: kicksecure, whonix (default).

-u, --guest-version=version

        Specify the guest version. If none is provided, the default is to query the API.

-i, --interface=interface

        Define the guest interface. Options: cli, lxqt (default).

-m, --hypervisor=hypervisor

        Choose the hypervisor for the guest. Options: kvm, virtualbox (default).

--oracle-repo

        Use the Oracle repository for VirtualBox. This is the default for Fedora-based
        distributions. It's optional for Debian-based ones but may be set by developers
        in the future if the Debian repository discontinues the VirtualBox package.

-o, --onion

        Route requests through the Tor onion network whenever possible.

-s, --socks-proxy=proxy

        Define a TCP SOCKS proxy for requests in the format "host:addr". If not specified
        and Tor onion routing is enabled, it defaults to TOR_SOCKS_HOST:TOR_SOCKS_PORT.
        If this fails, it defaults to host 127.0.0.1 and checks for TBB on port 9151
        or the system's tor on port 9050.

-l, --log-level=level

        Define the logging level. Options: debug, info, notice (default), warn, error.
        Log messages below the specified level are displayed.

-k, --no-boot

        Prevent the guest from booting after the installation. By default, the installer prompts
        to start the guest. In non-interactive mode, the guest starts automatically.

--no-import

        Skip the importation of the guest. By default, if the guest hasn't been imported, it will be.

--import-only=vm

        Import only a specific Virtual Machine when the guest is Whonix.
        Options: gateway, workstation, both.

--redownload

        Force a new download even if a flag indicates a previous successful download.

--destroy-existing-guest

        Deletes any existing virtual machine(s) and re-imports them.
        Warning: This action poses a risk of data loss as it involves
                 a complete reinstallation of the VM(s). Proceed with caution.

-P, --directory-prefix=directory

        Define the absolute path directory to store downloaded files. Defaults to
        $HOME/dist-installer-cli-download. The directory must exist and be writable by the user.
        Changing this directory without moving the previously downloaded files triggers a new download.

-n, --non-interactive

        Enable non-interactive mode. In this mode, all default options are assumed,
        including accepting the license and starting the guest.

--mirror=number

        Select a mirror based on its index number. If no mirror is selected,
        the default is mirror 0 for clearnet and mirror 0 for onion.
        Mirror indices:
          0 [DE] download.whonix.org (onion available)
          1 [DK] mirrors.dotsrc.org (onion available)
          2 [HU] quantum-mirror.hu

--virtualbox-only

        Only download and install VirtualBox.

--allow-errors

        Enable dirty mode, where the program continues despite errors.

--no-show-errors

        Suppress error messages.

--ci

        Enable CI mode for testing within Continuous Integration (CI) environments.

--testers

        Download the tester's version.

-D, --dev

        Activate development mode, which sets the default download version to an empty image.

-d, --dry-run

        Simulate a run without executing impactful actions.

-t, --getopt

        Display parsed options and exit.

-V, --version

        Display the version number and exit.

-h, --help

        Display help for commands and exit.

EXAMPLES
To install Whonix LXQt for KVM:

        $ dist-installer-cli --guest=whonix --interface=lxqt --hypervisor=kvm

To install the default configuration using Tor onion routing and a SOCKS proxy:

        $ dist-installer-cli --onion --socks-proxy=127.0.0.1:9050

To install the default configuration non-interactively and display info messages:

        $ dist-installer-cli --non-interactive --log-level=info

EXIT CODES
The installer returns the exit code of the last command executed. Some command exit codes might clash with the script's exit code, which would be considered a bug. Exit codes for curl and rsync are reserved to avoid conflicts and simplify debugging.

    1       General error.
    2       Unrecognized option or incorrect usage.
    3-35    Rsync errors.
    3-96    Curl errors.
    100     License declined by the user.
    101     Unsupported system.
    102     Virtual machines already exist.
    103     Download failure.
    104     Digital signature verification failure.
    105     Virtual machine import failure.
    106     Failed to start virtual machines due to anticipated virtualization issues.
    107     Failed to start virtual machines due to unforeseen issues.
    108     Oracle VirtualBox package found but option `--oracle-repo` was not provided.
    109     Oracle VirtualBox installed from tarball/source, but messing with packages installed from source can have unexpected results.

AUTHOR
This man page was authored by grass (grass@danwin1210.de).

WWW
For more information, visit: https://www.whonix.org/wiki/Dev/Linux_Installer

SEE ALSO
curl(1), sha512sum(1), signify-openbsd(1), qemu(1), kvm(1)