#!/bin/bash
# SPDX-Version: 3.0
# SPDX-CreationInfo: 2025-06-25; WEIDNER, Marc S.; <msw@coresecret.dev>
# SPDX-ExternalRef: GIT https://git.coresecret.dev/msw/CISS.debian.live.builder.git
# SPDX-FileContributor: WEIDNER, Marc S.; Centurion Intelligence Consulting Agency
# SPDX-FileCopyrightText: 2024-2025; WEIDNER, Marc S.; <msw@coresecret.dev>
# SPDX-FileType: SOURCE
# SPDX-License-Identifier: EUPL-1.2 OR LicenseRef-CCLA-1.0
# SPDX-LicenseComment: This file is part of the CISS.debian.installer.secure framework.
# SPDX-PackageName: CISS.debian.live.builder
# SPDX-Security-Contact: security@coresecret.eu

#######################################
# Usage Wrapper CISS.debian.live.builder
# Globals:
#   None
# Arguments:
#   None
# Returns:
#   0: on success
#######################################
usage() {
  # shellcheck disable=SC2155
  declare var_cols=$(tput cols 2>/dev/null || echo 80)

  #######################################
  # Header, Footer wrapper for dynamical output.
  # Arguments:
  #   1: Text.
  #   2: Width of Terminal.
  #######################################
  center() {
    declare var_text="$1"
    declare var_width="$2"
    declare var_padding=$(( (var_width - ${#var_text}) / 2 ))
    printf "%*s%s%*s\n" "${var_padding}" "" "${var_text}" "${var_padding}" ""
  }

  # shellcheck disable=SC2155
  declare var_header=$(center "CDLB(1)                        CISS.debian.live.builder                        CDLB(1)" "${var_cols}")
  # shellcheck disable=SC2155
  declare var_footer=$(center "V8.13.408.2025.11.13                        2025-11-06                         CDLB(1)" "${var_cols}")

  {
    echo -e "\e[1;97m${var_header}\e[0m"
    echo
    echo -e "\e[92mCISS.debian.live.builder from https://git.coresecret.dev/msw \e[0m"
    echo -e "\e[92mMaster V8.13.408.2025.11.13\e[0m"
    echo -e "\e[92mA lightweight Shell Wrapper for building a hardened Debian Live ISO Image.\e[0m"
    echo
    echo -e "\e[97m(c) Marc S. Weidner, 2018 - 2025 \e[0m"
    echo -e "\e[97m(p) Centurion Press, 2024 - 2025 \e[0m"
    echo
    echo -e "\e[97m${0} <option>, where <option> is one or more of: \e[0m"
    echo
    echo -e "\e[97m  --help, -h \e[0m"
    echo "    What you're looking at."
    echo
    echo -e "\e[97m  --autobuild=*, -a=* \e[0m"
    echo "    Headless mode. Skip the dialog wrapper, provider note screen and interactive kernel selector dialog."
    echo "    Change '*' to your desired Linux kernel and trim the 'linux-image-' string to select a specific kernel,"
    echo "    e.g. '--autobuild=6.12.30+bpo-amd64'."
    echo
    echo -e "\e[97m  --architecture <STRING> one of <amd64 | arm64> \e[0m"
    echo "    A string reflecting the architecture of the Live System."
    echo "    MUST be provided."
    echo
    echo -e "\e[97m  --build-directory </path/to/build_directory> \e[0m"
    echo "    Where the Debian Live Build Image should be generated. RECOMMENDED path: </opt/cdlb>"
    echo "    MUST be provided."
    echo
    echo -e "\e[97m  --change-splash <STRING> one of <club | hexagon>\e[0m"
    echo "    A string reflecting the Grub Boot Screen Splash you want to use. If omitted defaults to:"
    echo "    <./.archive/background/club.png>"
    echo
    echo -e "\e[97m  --cdi\e[0m"
    echo "    This option creates a boot menu entry that starts the forthcoming 'CISS.debian.installer', which is executed"
    echo "    once the system has successfully booted up."
    echo
    echo -e "\e[97m  --contact, -c\ e[0m"
    echo "    Show author contact information."
    echo
    echo -e "\e[97m  --control <STRING>\e[0m"
    echo "    A string, that reflects the version of your Live ISO Image."
    echo "    MUST be provided."
    echo
    echo -e "\e[97m  --debug, -d \e[0m"
    echo "    Enables debug logging for the main program routine. Detailed logging information are written to:"
    echo "    </tmp/ciss_live_builder_$$.log>"
    echo
    echo -e "\e[97m  --dhcp-centurion \e[0m"
    echo "    If a DHCP lease is provided, the provider's name server will be overridden and the hardened, privacy-focused "
    echo "    Centurion DNS servers will be used instead:"
    echo "      - https://dns01.eddns.eu/"
    echo "      - https://dns02.eddns.de/"
    echo "      - https://dns03.eddns.eu/"
    echo
    echo -e "\e[97m  --jump-host <IP | IP | ... > \e[0m"
    echo "    Provide up to 10 IPs for '/etc/host.allow' whitelisting of SSH access. Could be either IPv4 and / or IPv6 "
    echo "    addresses and / or CCDIR notation. If provided, than it MUST be a <SPACE> separated list."
    echo "    IPv6 addresses MUST be encapsulated with [], e.g., [1234::abcd]/64."
    echo
    echo -e "\e[97m  --key_age=* \e[0m"
    echo "    The SOPS AGE private keyring for decryption operations. Change '*' to your desired SOPS AGE key file."
    echo "    File MUST be placed in:"
    echo "    </dev/shm/cdlb_secrets>"
    echo
    echo -e "\e[97m  --key_luks=* \e[0m"
    echo "    The LUKS encryption / decryption passphrase for '/'-fs-encryption. Change '*' to your desired passphrase file."
    echo "    File MUST be placed in:"
    echo "    </dev/shm/cdlb_secrets>"
    echo
    echo -e "\e[97m  --log-statistics-only\e[0m"
    echo "    Provides statistic only after successful building a CISS.debian.live-ISO. While enabling '--log-statistics-only'"
    echo "    the argument '--build-directory' MUST be provided."
    echo
    echo -e "\e[97m  --provider-netcup-ipv6 \e[0m"
    echo "    Activates IPv6 support for Netcup Root Server. One unique IPv6 address MUST be provided in this case and MUST be"
    echo "    encapsulated with [], e.g., [1234::abcd]."
    echo
    echo -e "\e[97m  --renice-priority <PRIORITY> \e[0m"
    echo "    Reset the nice priority value of the script and all its children to the desired <PRIORITY>. MUST be an integer"
    echo "    between '-19' and 19. Negative (higher) values MUST be enclosed in double quotes '\"'."
    echo
    echo -e "\e[97m  --reionice-priority <CLASS> <PRIORITY> \e[0m"
    echo "    Reset the ionice priority value of the script and all its children to the desired <CLASS>. MUST be an integer:"
    echo "      1: realtime"
    echo "      2: best-effort"
    echo "      3: idle"
    echo "    Defaults to '2'."
    echo "    Whereas <PRIORITY> MUST be an integer as well between:"
    echo "      0: highest priority and"
    echo "      7: lowest priority."
    echo "    Defaults to '4'."
    echo "    A real-time I/O process can significantly slow down other processes or even cause them to starve if it"
    echo "    continuously requests I/O."
    echo
    echo -e "\e[97m  --root-password-file </dev/shm/cdlb_secrets/password.txt>> \e[0m"
    echo "    Password file for 'root', if given, MUST be a string of 42 to 64 characters."
    echo "    If the argument is omitted, no further login authentication is required for the local console."
    echo "    MUST be placed in:"
    echo "    </dev/shm/cdlb_secrets/password.txt>"
    echo
    echo -e "\e[97m  --signing_key=* and --signing_key_fpr=*. Optional: --signing_key_pass=* --signing_ca=* \e[0m"
    echo "    The GPG private keyring that should be used for signing artifacts such as checksum hashes and scripts is"
    echo "    specified via '--signing_key=*'. If the keyring is protected, then provide the passphrase in its own file."
    echo "    Specify the fingerprint of the key to use via '--signing_key_fpr=*'."
    echo "    Optionally import an offline GPG CA signing public key via: '--signing_ca=*'."
    echo "    Change '*' to your desired files / fingerprint. Files MUST be placed in:"
    echo "    </dev/shm/cdlb_secrets>"
    echo
    echo -e "\e[97m  --sshfp \e[0m"
    echo "    Desired SSH id-files that should be incorporated in '/root/.ssh/id*'."
    echo "    Desired SSH host-files that should be incorporated in '/etc/ssh/ssh_host_*'."
    echo "    The respective id-files and / or host-files MUST be placed in:"
    echo "    </dev/shm/cdlb_secrets/id*> / </dev/shm/cdlb_secrets/ssh_host_*>"
    echo
    echo -e "\e[97m  --ssh-port <INTEGER> \e[0m"
    echo "    The desired Port SSH should listen to."
    echo "    If not provided defaults to Port '22'."
    echo
    echo -e "\e[97m  --ssh-pubkey </dev/shm/cdlb_secrets/> \e[0m"
    echo "    Imports the SSH Public Key from the file 'authorized_keys' into the Live ISO."
    echo "    Key file MUST be placed in:"
    echo "    </dev/shm/cdlb_secrets/authorized_keys>"
    echo
    echo -e "\e[97m  --trixie \e[0m"
    echo "    Creates a Debian Trixie Live ISO. If omitted defaults to 'Trixie'. No other Debian Version is supported."
    echo
    echo -e "\e[97m  --version, -v \e[0m"
    echo "    Show version of ${0}."
    echo
    echo -e "\e[93m💡 Notes:\e[0m"
    echo -e "\e[93m🔵 You MUST be 'root' to run this script.\e[0m"
    echo
    echo -e "\e[95m💷 Please consider donating to my work at: \e[0m"
    echo -e "\e[95m🌐 https://coresecret.eu/spenden/ \e[0m"
    echo
    echo -e "\e[1;97m${var_footer}\e[0m"
  } | less -R

  return 0
}
### Prevents accidental 'unset -f'.
# shellcheck disable=SC2034
readonly -f usage
# vim: number et ts=2 sw=2 sts=2 ai tw=128 ft=sh
