From a30f20b9b52dcf5582d41dc6a4a182547dbb4879 Mon Sep 17 00:00:00 2001 From: Seth Grover Date: Thu, 14 Mar 2024 14:40:36 -0600 Subject: [PATCH] idaholab/Malcolm#440, rearrange download page --- .../workflows/nginx-build-and-push-ghcr.yml | 1 - _config.yml | 2 +- _layouts/default.html | 2 +- docs/README.md | 3 + docs/download.md | 73 ++++++++++++------- docs/kubernetes.md | 2 +- docs/malcolm-hedgehog-e2e-iso-install.md | 6 +- docs/ubuntu-install-example.md | 4 +- 8 files changed, 57 insertions(+), 36 deletions(-) diff --git a/.github/workflows/nginx-build-and-push-ghcr.yml b/.github/workflows/nginx-build-and-push-ghcr.yml index 2343e6f31..708d7fdd0 100644 --- a/.github/workflows/nginx-build-and-push-ghcr.yml +++ b/.github/workflows/nginx-build-and-push-ghcr.yml @@ -21,7 +21,6 @@ on: - '_includes/**' - '_layouts/**' - 'docs/**' - - '!docs/download.md' - 'Gemfile' - 'README.md' workflow_dispatch: diff --git a/_config.yml b/_config.yml index cc752665c..41ff84c2f 100644 --- a/_config.yml +++ b/_config.yml @@ -3,7 +3,6 @@ title: Malcolm description: A powerful, easily deployable network traffic analysis tool suite logo: docs/images/logo/Malcolm_outline_banner_dark.png remote_theme: pages-themes/minimal@v0.2.0 -external_download_url: https://malcolm.fyi/docs/download.html youtube_url: https://www.youtube.com/@MalcolmNetworkTrafficAnalysis mastodon: id: malcolm@malcolm.fyi @@ -17,6 +16,7 @@ components_docs_uri: docs/components.html configuring_docs_uri: docs/malcolm-preparation.html contributing_docs_uri: docs/contributing-guide.html dashboards_docs_uri: docs/dashboards.html +download_docs_uri: docs/download.html#DownloadISOs hardening_docs_uri: docs/hardening.html hedgehog_docs_uri: docs/hedgehog.html live_analysis_docs_uri: docs/live-analysis.html diff --git a/_layouts/default.html b/_layouts/default.html index 96b0304f2..0ee5513ce 100644 --- a/_layouts/default.html +++ b/_layouts/default.html @@ -72,7 +72,7 @@

{{ site.title | default: site.github.repo {% endif %} diff --git a/docs/README.md b/docs/README.md index 2d2f14741..4db0c10f3 100644 --- a/docs/README.md +++ b/docs/README.md @@ -19,6 +19,9 @@ Malcolm can also easily be deployed locally on an ordinary consumer workstation - [User interface](quickstart.md#UserInterfaceURLs) * [Components](components.md#Components) * [Supported Protocols](protocols.md#Protocols) +* [Downloading Malcolm](download.md#DownloadMalcolm) + - [Docker images](download.md#DownloadDockerImages) + - [Installer ISOs](download.md#DownloadISOs) * [Development](development.md#Development) - [Building from source](development.md#Build) - [Pre-Packaged installation files](development.md#Packager) diff --git a/docs/download.md b/docs/download.md index 3eb34465a..4fcec515f 100644 --- a/docs/download.md +++ b/docs/download.md @@ -1,47 +1,68 @@ -# Downloads +# Downloading Malcolm -## Malcolm +* [Docker images](#DownloadDockerImages) +* [Installer ISOs](#DownloadISOs) + - [Joining split ISOs](#JoinISOs) + - [Warning](#ISOsWarning) -### Docker images +## Docker images -Malcolm operates as a cluster of Docker containers, isolated sandboxes which each serve a dedicated function of the system. Its Docker images can be pulled from [GitHub](https://github.com/orgs/idaholab/packages?repo_name=Malcolm) or built from source by following the instructions in the [Quick Start](quickstart.md#QuickStart) section of the documentation. +Malcolm operates as a cluster of Docker containers, isolated sandboxes which each serve a dedicated function of the system. These Docker images can be pulled from [GitHub](https://github.com/orgs/idaholab/packages?repo_name=Malcolm) by running `docker compose --profile malcolm pull` from within the Malcolm installation directory, or they can be built from source by following the instructions in the [Quick Start](quickstart.md#QuickStart) section of the documentation. -### Installer ISO +## Installer ISOs Malcolm's Docker-based deployment model makes Malcolm able to run on a variety of platforms. However, in some circumstances (for example, as a long-running appliance as part of a security operations center, or inside of a virtual machine) it may be desirable to install Malcolm as a dedicated standalone installation. -Malcolm can be [packaged](malcolm-iso.md#ISOBuild) into an [installer ISO](malcolm-iso.md#ISO) based on the current [stable release](https://wiki.debian.org/DebianStable) of [Debian](https://www.debian.org/). This [customized Debian installation](https://wiki.debian.org/DebianLive) is preconfigured with the bare minimum software needed to run Malcolm. +Malcolm can be packaged into an [installer ISO](malcolm-iso.md#ISO) based on the current [stable release](https://wiki.debian.org/DebianStable) of [Debian](https://www.debian.org/). This [customized Debian installation](https://wiki.debian.org/DebianLive) is preconfigured with the bare minimum software needed to run Malcolm. -While official downloads of the Malcolm installer ISO are not provided, an **unofficial build** of the ISO installer for the [latest stable release]({{ site.github.repository_url }}/releases/latest) is available for download here. +### Joining split ISOs -| ISO | SHA256 | -|---|---| -| [malcolm-24.03.1.iso](/iso/malcolm-24.03.1.iso) (5.1GiB) | [`xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`](/iso/malcolm-24.03.1.iso.sha256.txt) | +ISOs can be downloaded from [Malcolm's releases page]({{ site.github.repository_url }}/releases/latest) on GitHub. Due to [limits on individual files](https://docs.github.com/en/repositories/releasing-projects-on-github/about-releases#storage-and-bandwidth-quotas) in GitHub releases, these ISO files have been split into 2GB chunks and can be reassembled with scripts provided for both Bash ([release_cleaver.sh]({{ site.github.repository_url }}/blob/{{ site.github.build_revision }}/scripts/release_cleaver.sh)) and PowerShell ([release_cleaver.ps1]({{ site.github.repository_url }}/blob/{{ site.github.build_revision }}/scripts/release_cleaver.ps1)). -## Hedgehog Linux +For example, having downloaded the following files from the GitHub release page for Malcolm, the script will join the component files and check the resulting ISO's SHA256 sum: -### Installer ISO +```bash +$ ls -l +total 5446119424 +-rw-r--r-- 1 user user 2000000000 Mar 14 20:03 malcolm-24.03.0.iso.01 +-rw-r--r-- 1 user user 2000000000 Mar 14 20:03 malcolm-24.03.0.iso.02 +-rw-r--r-- 1 user user 1446103040 Mar 14 20:03 malcolm-24.03.0.iso.03 +-rw-r--r-- 1 user user 86 Mar 14 20:03 malcolm-24.03.0.iso.sha +-rwxr-xr-x 1 user user 3133 Mar 14 20:02 release_cleaver.sh -[Instructions are provided](hedgehog-iso-build.md#HedgehogISOBuild) to generate the Hedgehog Linux ISO from source. While official downloads of the Hedgehog Linux ISO are not provided, an **unofficial build** of the ISO installer for the latest stable release is available for download here. +$ ./release_cleaver.sh malcolm-24.03.0.iso.* +Joining... +malcolm-24.03.0.iso: OK -| ISO | SHA256 | -|---|---| -| [hedgehog-24.03.1.iso](/iso/hedgehog-24.03.1.iso) (2.5GiB) | [`xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`](/iso/hedgehog-24.03.1.iso.sha256.txt) | +$ ls -l *.iso +-rw-r--r-- 1 user user 5446103040 Mar 14 20:04 malcolm-24.03.0.iso +``` -### Raspberry Pi 4 Image +Similarly, in Microsoft Windows using PowerShell: -[Instructions are provided](hedgehog-raspi-build.md#HedgehogRaspiBuild) to generate the Hedgehog Linux Raspberry Pi image from source. While official downloads of the Hedgehog Linux image are not provided, an **unofficial build** of the image for the latest stable release is available for download here. This image is compatible with Raspberry Pi 4 models. +```powershell +PS C:\Download> dir -| Image | SHA256 | -|---|---| -| [hedgehog-24.03.1_raspi_4.img.xz](/iso/hedgehog-24.03.1_raspi_4.img.xz) (1.4GiB) | [`xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`](/iso/hedgehog-24.03.1_raspi_4.img.xz.sha256.txt) | +Mode LastWriteTime Length Name +---- ------------- ------ ---- +-a---- 3/14/2024 2:16 PM 2000000000 malcolm-24.03.0.iso.01 +-a---- 3/14/2024 2:16 PM 2000000000 malcolm-24.03.0.iso.02 +-a---- 3/14/2024 2:16 PM 1446103040 malcolm-24.03.0.iso.03 +-a---- 3/14/2024 2:16 PM 176 malcolm-24.03.0.iso.sha +-a---- 3/14/2024 2:00 PM 6806 release_cleaver.ps1 -## Warning -Please check any files you may have downloaded from the links on this page against the SHA256 sums provided to verify the integrity of the downloads. +PS C:\Download> .\release_cleaver.ps1 .\malcolm-24.03.0.iso.* +Joining... +"malcolm-24.03.0.iso" OK -Read carefully the installation documentation for [Malcolm](malcolm-iso.md#ISOInstallation) and/or [Hedgehog Linux](hedgehog-installation.md#HedgehogInstallation). The ISO media boot on systems that support EFI-mode booting. The installer is designed to require as little user input as possible. For this reason, there are NO user prompts and confirmations about partitioning and reformatting hard disks for use by the operating system. The installer assumes that all non-removable storage media (eg., SSD, HDD, NVMe, etc.) are available for use and ⛔🆘😭💀 ***will partition and format them without warning*** 💀😭🆘⛔. +PS C:\Download> dir *.iso + +Mode LastWriteTime Length Name +---- ------------- ------ ---- +-a---- 3/14/2024 2:17 PM 5446103040 malcolm-24.03.0.iso +``` -## Disclaimer +### Warning -The terms of [Malcolm's license]({{ site.github.repository_url }}/blob/{{ site.github.build_revision }}/LICENSE.txt) and [release notice]({{ site.github.repository_url }}/blob/{{ site.github.build_revision }}/NOTICE.txt) also apply to these unofficial builds of the Malcolm and Hedgehog Linux installer ISOs: neither the organizations funding Malcolm's development, its developers nor the maintainer of this site makes any warranty, express or implied, or assumes any legal liability or responsibility for the accuracy, completeness or usefulness of any data, apparatus or process disclosed therein. +Read carefully the installation documentation for [Malcolm](malcolm-iso.md#ISOInstallation) and/or [Hedgehog Linux](hedgehog-installation.md#HedgehogInstallation). The ISO media boot on systems that support EFI-mode booting. The installer is designed to require as little user input as possible. For this reason, there are NO user prompts and confirmations about partitioning and reformatting hard disks for use by the operating system. The installer assumes that all non-removable storage media (eg., SSD, HDD, NVMe, etc.) are available for use and ⛔🆘😭💀 ***will partition and format them without warning*** 💀😭🆘⛔. diff --git a/docs/kubernetes.md b/docs/kubernetes.md index eb7cae6c9..3856f5966 100644 --- a/docs/kubernetes.md +++ b/docs/kubernetes.md @@ -302,7 +302,7 @@ Malcolm's control scripts require the [official Python 3 client library for Kube # Deployment Example -Here is a basic step-by-step example illustrating how to deploy Malcolm with Kubernetes. For the sake of simplicity, this example uses Vagrant (see [kubernetes/vagrant/Vagrantfile]({{ site.github.repository_url }}/blob/{{ site.github.build_revision }}/kubernetes/vagrant/Vagrantfile)) to create a virtualized Kubernetes cluster with one control plane node and two worker nodes. It assumes users have downloaded and extracted the [release tarball]({{ site.github.repository_url }}/releases) or used `./scripts/malcolm_appliance_packager.sh` to package up the files needed to run Malcolm. +Here is a basic step-by-step example illustrating how to deploy Malcolm with Kubernetes. For the sake of simplicity, this example uses Vagrant (see [kubernetes/vagrant/Vagrantfile]({{ site.github.repository_url }}/blob/{{ site.github.build_revision }}/kubernetes/vagrant/Vagrantfile)) to create a virtualized Kubernetes cluster with one control plane node and two worker nodes. It assumes users have downloaded and extracted the [release tarball]({{ site.github.repository_url }}/releases/latest) or used `./scripts/malcolm_appliance_packager.sh` to package up the files needed to run Malcolm. ``` $ ls -l diff --git a/docs/malcolm-hedgehog-e2e-iso-install.md b/docs/malcolm-hedgehog-e2e-iso-install.md index 71a303031..778cd2f55 100644 --- a/docs/malcolm-hedgehog-e2e-iso-install.md +++ b/docs/malcolm-hedgehog-e2e-iso-install.md @@ -34,11 +34,9 @@ In contrast to using the ISO installer, Malcolm can also be installed "natively" ## Obtaining the Installation ISOs -Malcolm can be [packaged](malcolm-iso.md#ISOBuild) into an [installer ISO](malcolm-iso.md#ISO) based on the current [stable release](https://wiki.debian.org/DebianStable) of [Debian](https://www.debian.org/). This [customized Debian installation](https://wiki.debian.org/DebianLive) is preconfigured with the bare minimum software needed to run Malcolm. +Please see [**Downloading Malcolm**](download.md#DownloadMalcolm) for instructions on how to obtain the Malcolm and Hedgehog Linux installation ISOs. -Similar instructions exist for generating the [installer ISO](hedgehog-iso-build.md#HedgehogISOBuild) for [Hedgehog Linux](hedgehog.md), Malcolm's dedicated network sensor appliance OS. - -While official downloads of the Malcolm installer ISO are not provided, an **unofficial build** of the ISO installer for the [latest stable release]({{ site.github.repository_url }}/releases) is available for [download here]({{ site.external_download_url }}). If downloading the unofficial builds, be sure to verify the integrity of ISO files against the SHA256 sums provided on the download page. +As an alternative to the official release ISOs, instructions are provided for building the [Malcolm insaller ISO](malcolm-iso.md#ISOBuild) and [Hedgehog Linux installer ISO](hedgehog-iso-build.md#HedgehogISOBuild) (Malcolm's dedicated [network sensor appliance OS](hedgehog.md)) from scratch. ## "Burning" the Installation ISOs to USB Flash Drive diff --git a/docs/ubuntu-install-example.md b/docs/ubuntu-install-example.md index 297020787..138a3d499 100644 --- a/docs/ubuntu-install-example.md +++ b/docs/ubuntu-install-example.md @@ -6,9 +6,9 @@ For a more in-depth guide convering installing both Malcolm and a [Hedgehog Linu The commands in this example should be executed as a non-root user. -Use `git` to clone Malcolm into a local working copy, or download and extract the artifacts from the [latest release]({{ site.github.repository_url }}/releases). +Use `git` to clone Malcolm into a local working copy, or download and extract the artifacts from the [latest release]({{ site.github.repository_url }}/releases/latest). -To install Malcolm from the latest Malcolm release, browse to the [Malcolm releases page on GitHub]({{ site.github.repository_url }}/releases) and download at a minimum the files ending in `.py` and the `malcolm_YYYYMMDD_HHNNSS_xxxxxxx.tar.gz` file, then navigate to the downloads directory: +To install Malcolm from the latest Malcolm release, browse to the [Malcolm releases page on GitHub]({{ site.github.repository_url }}/releases/latest) and download at a minimum the files ending in `.py` and the `malcolm_YYYYMMDD_HHNNSS_xxxxxxx.tar.gz` file, then navigate to the downloads directory: ``` user@host:~$ cd Downloads/ user@host:~/Downloads$ ls