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 at or above 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.

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

--noupdate

    Skip package manager list update. For development only.

--noupgrade

    Ignore pending upgrades. For development only.

--user=username

    Specify the user to install the distribution VM under.


    Useful when running as a different user (e.g. sysmaint).

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