From 0dbd62db5584b8233b89044041bcb9dfa2ec1e80 Mon Sep 17 00:00:00 2001
From: Greg DiCristofaro <gregd@basistech.com>
Date: Mon, 22 Aug 2022 09:11:28 -0400
Subject: [PATCH] update for Running_Linux_OSX doc

---
 README_LINUX_OSX.md                           |  22 ----
 .../README.md => Running_Linux_OSX.md         |  76 ++++++++----
 Running_Linux_OSX.txt                         | 108 +-----------------
 .../add_macos_jna.sh                          |   2 +-
 .../install_application_from_zip.sh           |   0
 .../install_prereqs_macos.sh                  |   0
 .../install_prereqs_ubuntu.sh                 |   0
 .../install_tsk_from_src.sh                   |   0
 8 files changed, 58 insertions(+), 150 deletions(-)
 delete mode 100644 README_LINUX_OSX.md
 rename unix_install_scripts/README.md => Running_Linux_OSX.md (57%)
 rename unix_install_scripts/add_osx_jna.sh => linux_macos_install_scripts/add_macos_jna.sh (84%)
 rename {unix_install_scripts => linux_macos_install_scripts}/install_application_from_zip.sh (100%)
 rename unix_install_scripts/install_prereqs_osx.sh => linux_macos_install_scripts/install_prereqs_macos.sh (100%)
 rename {unix_install_scripts => linux_macos_install_scripts}/install_prereqs_ubuntu.sh (100%)
 rename {unix_install_scripts => linux_macos_install_scripts}/install_tsk_from_src.sh (100%)

diff --git a/README_LINUX_OSX.md b/README_LINUX_OSX.md
deleted file mode 100644
index 834288b201..0000000000
--- a/README_LINUX_OSX.md
+++ /dev/null
@@ -1,22 +0,0 @@
-Most of the Autopsy development occurs to be run on Windows systems, but it is possible to run Autopsy on Linux and OS X.  This file contains the instructions for building Autopsy on those platforms and getting it working.
-
-# Prerequisites
-
-You need the following:
-- X
-- Y
-
-TODO
-
-
-# Building
-## Building The Sleuth Kit
-
-TODO
-
-## Building Autopsy
-
-TODO
-
-
-
diff --git a/unix_install_scripts/README.md b/Running_Linux_OSX.md
similarity index 57%
rename from unix_install_scripts/README.md
rename to Running_Linux_OSX.md
index c94919899a..d576075ce4 100644
--- a/unix_install_scripts/README.md
+++ b/Running_Linux_OSX.md
@@ -1,11 +1,11 @@
 # Overview
-*The installation process requires some [prerequisites](#installing-prerequisites), [Sleuthkit](#install-sleuthkit), and installing [Autopsy itself](#install-autopsy).  If using Windows, there is a pre-built installer bundling all dependencies that can be found in the [Autopsy downloads section](https://www.autopsy.com/download/) or in the [Releases section on GitHub](https://github.com/sleuthkit/autopsy/releases/).*
+*The installation process requires some [prerequisites](#installing-prerequisites), [The Sleuth Kit](#install-sleuthkit), and installing [Autopsy itself](#install-autopsy).  If using Windows, there is a pre-built installer bundling all dependencies that can be found in the [Autopsy downloads section](https://www.autopsy.com/download/) or in the [Releases section on GitHub](https://github.com/sleuthkit/autopsy/releases/).*
 
 # Installing Prerequisites
 
-## On OS X
+## On macOS
 
-*A script to install these dependencies that can be found [here](install_prereqs_osx.sh).*
+*A script to install these dependencies that can be found [here](./linux_macos_install_scripts/install_prereqs_macos.sh).*
 - Using [Homebrew](https://brew.sh/), install dependencies that have formulas:
   ```
   brew install ant automake libtool afflib libewf postgresql testdisk
@@ -18,6 +18,13 @@
   ```
   brew install --cask liberica-jdk8-full
   ```
+- - Confirm that java has been successfully installed by running `java -version`.  You should get a result like the following:
+  ```
+  % java -version
+  openjdk version "1.8.0_342"
+  OpenJDK Runtime Environment (build 1.8.0_342-b07)
+  OpenJDK 64-Bit Server VM (build 25.342-b07, mixed mode)
+  ```
 - You will need the java path for properly setting up autopsy.  You can get the path to java by calling:
   ```
   /usr/libexec/java_home -v 1.8
@@ -26,7 +33,7 @@
   
 ## On Linux (Ubuntu / Debian-based)
 
-*A script to install these dependencies that can be found [here](install_prereqs_ubuntu.sh).*
+*A script to install these dependencies that can be found [here](./linux_macos_install_scripts/install_prereqs_ubuntu.sh).*
 - You will need to include some repositories in order to install this software.  One way to do that is to uncomment lines in your `sources.list`:
   ```
   sudo sed -Ei 's/^# deb-src /deb-src /' /etc/apt/sources.list
@@ -51,12 +58,21 @@
   sudo apt -y install bellsoft-java8-full && \
   popd
   ```
+- Confirm that java has been successfully installed by running `java -version`.  You should get a result like the following:
+  ```
+  % java -version
+  openjdk version "1.8.0_342"
+  OpenJDK Runtime Environment (build 1.8.0_342-b07)
+  OpenJDK 64-Bit Server VM (build 25.342-b07, mixed mode)
+  ```
 - Take note of the location of the java 1.8 install.  This will be necessary to properly setup Autopsy.  If using the recommended method, the path should be `/usr/lib/jvm/bellsoft-java8-full-amd64`
 
-# Install Sleuthkit
+# Install The Sleuth Kit
+
+The Sleuth Kit must be installed before trying to install Autopsy.  If you are on a Debian-like system (i.e. Ubuntu) you can download the most recent deb file from the [github release section](https://github.com/sleuthkit/sleuthkit/releases), and install by running something like `sudo apt install ./sleuthkit-java_4.11.1-1_amd64.deb`.  Otherwise, you can follow the directions below to install The Sleuth Kit from source code.
 
-## Install Sleuthkit from Source
-*A script to install these dependencies on Unix-like systems (i.e. OS X, Linux) that can be found [here](install_tsk_from_src.sh).*
+## Install The Sleuth Kit from Source
+*A script to install these dependencies on Unix-like systems (i.e. macOS, Linux) that can be found [here](./linux_macos_install_scripts/install_tsk_from_src.sh).*
 - Please ensure you have all the prerequisites installed on your system (see the directions [here](#installing-prerequisites)).
 - If you don't have a copy of the repository on your local machine, clone it (this requires git):
   ```
@@ -66,7 +82,7 @@
   ```
   git checkout <YOUR BRANCH HERE> && git pull
   ```
-- Then, with the sleuthkit repo as your working directory, you can build with:
+- Then, with The Sleuth Kit repo as your working directory, you can build with:
   ```
   ./bootstrap && ./configure && make
   ```
@@ -78,7 +94,7 @@
 # Install Autopsy
 
 ## Create Autopsy Zip File from Source
-*In most instances, you should download the Autopsy Zip file from the [Autopsy downloads section](https://www.autopsy.com/download/) or in the [Releases section on GitHub](https://github.com/sleuthkit/autopsy/releases/), but if you have a special use case you can do the following.  Please make sure you have the [prerequisites installed](#installing-prerequisites) and have [installed Sleuthkit](#install-sleuthkit).* 
+*In most instances, you should download the Autopsy Zip file from the [Autopsy downloads section](https://www.autopsy.com/download/) or in the [Releases section on GitHub](https://github.com/sleuthkit/autopsy/releases/), but if you have a special use case you can do the following.  Please make sure you have the [prerequisites installed](#installing-prerequisites) and have [installed The Sleuth Kit](#install-sleuthkit).* 
 - If you haven't already, clone the repo:
   ```
   git clone https://github.com/sleuthkit/autopsy.git
@@ -90,10 +106,10 @@
 - The zip file should be created within the `dist` folder of the Autopsy repository and will have the version in the name (i.e. `autopsy-4.18.0.zip`).
 
 ## Install Autopsy from Zip File
-*These instructions are for Unix-like systems like OS X and Linux.  If you are on Windows, there is an installer that can be downloaded from the [Autopsy downloads section](https://www.autopsy.com/download/) or in the [Releases section on GitHub](https://github.com/sleuthkit/autopsy/releases/). Please make sure you have the [prerequisites installed](#installing-prerequisites) and have [installed Sleuthkit](#install-sleuthkit). A script to perform these steps can be found [here](install_autopsy_from_zip.sh).*
+*These instructions are for Unix-like systems like macOS and Linux.  If you are on Windows, there is an installer that can be downloaded from the [Autopsy downloads section](https://www.autopsy.com/download/) or in the [Releases section on GitHub](https://github.com/sleuthkit/autopsy/releases/). Please make sure you have the [prerequisites installed](#installing-prerequisites) and have [installed The Sleuth Kit](#install-sleuthkit). A script to perform these steps can be found [here](./linux_macos_install_scripts/install_application_from_zip.sh).*
 
 - Download the zip file from the [Autopsy downloads section](https://www.autopsy.com/download/) or in the [Releases section on GitHub](https://github.com/sleuthkit/autopsy/releases/).  You can also create a zip file from source using [these directions](#create-autopsy-zip-file-from-source).
-- If you downloaded the zip file, you can verify the zip file with the [Sleuthkit key](https://sleuthkit.org/carrier.asc) and the related `.asc` file found in the [Releases section on GitHub](https://github.com/sleuthkit/autopsy/releases/).  For instance, you would use `autopsy-4.18.0.zip.asc` with `autopsy-4.18.0.zip`.  Here is an example where `$ASC_FILE` is the path to the `.asc` file and `$AUTOPSY_ZIP_PATH` is the path to the autopsy zip file:
+- If you downloaded the zip file, you can verify the zip file with the [The Sleuth Kit key](https://sleuthkit.org/carrier.asc) and the related `.asc` file found in the [Releases section on GitHub](https://github.com/sleuthkit/autopsy/releases/).  For instance, you would use `autopsy-4.18.0.zip.asc` with `autopsy-4.18.0.zip`.  Here is an example where `$ASC_FILE` is the path to the `.asc` file and `$AUTOPSY_ZIP_PATH` is the path to the autopsy zip file:
   ```
   mkdir -p ${VERIFY_DIR} && \
   pushd ${VERIFY_DIR} && \
@@ -114,16 +130,27 @@
   ```
 - At this point, you should be able to run Autopsy with the command `./autopsy` from within the `bin` directory of the extracted folder.
 
-## Setup OSX JNA paths
-A few features in Autopsy will only work (i.e. gstreamer) if the JNA paths are specified.  If you installed the necessary dependencies through Homebrew, you will want to either run this [script](add_osx_jna.sh) or manually add all the gstreamer lib and dependency lib paths to the env variable `jre_flags` with jre flag: `-Djna.library.path`.
+## Setup macOS JNA paths
+A few features in Autopsy will only work (i.e. gstreamer) if the JNA paths are specified.  If you installed the necessary dependencies through Homebrew, you will want to either run this [script](./linux_macos_install_scripts/add_macos_jna.sh) or manually add all the gstreamer lib and dependency lib paths to the env variable `jre_flags` with jre flag: `-Djna.library.path`.
 
-# Caveats
-- Not all current features in Autopsy are functional in a Linux and Mac environment including but not limited to:
-  - Recent Activity
-  - The LEAPP processors
-  - HEIF processing
 
-# Known Issues
+# Troubleshooting
+- If you see something like "Cannot create case: javafx/scene/paint/Color" it is an indication that Java FX
+  is not being found.  Confirm that the file `$JAVA_HOME/jre/lib/ext/jfxrt.jar` exists. If it does not exist, return to the Java
+  setup steps above.
+- If you see something like "An illegal reflective access operation has occurred" it is an indication that
+  the wrong version of Java is being used to run Autopsy.
+  Check the version of Java reported in the `messages.log` file in the log directory.  The log directory can be found by opening Autopsy, and, with no cases open, go to 'Help' > 'Open Log Folder'. `messages.log` should contain lines that looks like:
+  ```
+  Java; VM; Vendor        = 1.8.0_342; OpenJDK 64-Bit Server VM 25.342-b07; BellSoft
+  Runtime                 = OpenJDK Runtime Environment 1.8.0_342-b07
+  Java Home               = /usr/lib/jvm/bellsoft-java8-full-amd64/jre
+  ```
+
+  If your `messages.log` file indicates that Java 8 is not being used:
+  - Confirm that you have a version of Java 8 installed
+  - Confirm that your java path environment variable is set correctly.  Autopsy first uses the value of `jdkhome` in `<autopsy_install_location>/etc/autopsy.conf`, so look for an uncommented line (not starting with '#') that looks like `jdkhome=<java path>`.  If that is not set, check your `$JAVA_HOME` environment variable by running `echo $JAVA_HOME`.
+- If you see something like "cannot be opened because the developer cannot be verified." it is an indication that Gatekeeper is running and is stopping a file from being executed.  To fix this open a new terminal window and enter the following command `sudo spctl --master-disable`, you will be required to enter your password.  This will allow any program to be be downloaded from anywhere and executed.
 - On initial run, Autopsy shows a window that can appear behind the splash screen.  This looks like Autopsy has stalled during startup.  The easiest way to get around this issue for the first run is to run autopsy with the `--nosplash` flag, which will hide the splash screen on startup.  There will be a lag where no window appears for a bit, so please be patient.
 - If a script fails to run due to operation not permitted or something along those lines, you may need to run `chmod u+x <path to script>` from the command line to allow the script to run.
 - If you encounter an error like: `getcwd: cannot access parent directories: Operation not permitted` on Mac, you can do the following:
@@ -132,4 +159,13 @@ A few features in Autopsy will only work (i.e. gstreamer) if the JNA paths are s
   3. Click '+'
   4. Press 'cmd' + 'shift' + '.' to show hidden files
   5. Select `/bin/sh`
-  *Source: [Symscape](https://www.symscape.com/node/1727)*
\ No newline at end of file
+  *Source: [Symscape](https://www.symscape.com/node/1727)*
+
+# Known Issues
+- Not all current features in Autopsy are functional in a Linux and Mac environment including but not limited to:
+  - Recent Activity
+  - The LEAPP processors
+  - HEIF processing
+  - Timeline does not work on OS X
+  - Video thumbnails
+  - VHD and VMDK files not supported on OS X
diff --git a/Running_Linux_OSX.txt b/Running_Linux_OSX.txt
index 9dadd10e78..2a438728d3 100644
--- a/Running_Linux_OSX.txt
+++ b/Running_Linux_OSX.txt
@@ -1,110 +1,4 @@
-This document outlines how to run a packaged version of Autopsy on Linux or OS X.  It does not cover how to compile it from source or the Windows installer.
-
-
-* Prerequisites *
-
-The following need to be done at least once. They do not need to be repeated for each Autopsy release.
-
-- Install testdisk for photorec functionality
--- Linux:  % sudo apt-get install testdisk
--- OS X: % brew install testdisk
-
-- (Optional) Install ImageMagick for Apple's High Efficiency Photo (HEIC/HEIF) support.
--- OS X: % brew install imagemagick
--- Linux:
-     % sudo sed -Ei 's/^# deb-src /deb-src /' /etc/apt/sources.list
-
-     % sudo apt-get update
-     % sudo apt-get install build-essential autoconf libtool git-core
-     % sudo apt-get build-dep imagemagick libmagickcore-dev libde265 libheif
-
-     % cd /usr/src/ 
-
-     % sudo git clone https://github.com/strukturag/libde265.git 
-     % sudo git clone https://github.com/strukturag/libheif.git 
-
-     % cd libde265/ 
-     % sudo ./autogen.sh 
-     % sudo ./configure 
-     % sudo make 
-     % sudo make install 
-
-     % cd /usr/src/libheif/ 
-     % sudo ./autogen.sh 
-     % sudo ./configure 
-     % sudo make 
-     % sudo make install 
-
-     % cd /usr/src/ 
-     % sudo wget https://www.imagemagick.org/download/ImageMagick.tar.gz 
-     % sudo tar xf ImageMagick.tar.gz 
-
-     % cd ImageMagick-7*
-     % sudo ./configure --with-heic=yes 
-     % sudo make 
-     % sudo make install 
-
-     % sudo ldconfig  
-
-- Install the BellSoft Java 8 JRE and JavaFX 8 distribution and set JAVA_HOME.
-  * The BellSoft distribution bundles OpenJDK and OpenJFX. Other distributions we have tried either don't
-    bundle OpenJFX (AdoptOpenJDK) or don't include all necessary binaries (Amazon Corretto).
--- Linux:
-    1. Install BellSoft Java 8
-       % wget -q -O - https://download.bell-sw.com/pki/GPG-KEY-bellsoft | sudo apt-key add -
-       % echo "deb [arch=amd64] https://apt.bell-sw.com/ stable main" | sudo tee /etc/apt/sources.list.d/bellsoft.list
-       % sudo apt-get update
-       % sudo apt-get install bellsoft-java8-full
-    2. Set JAVA_HOME
-       % export JAVA_HOME=/usr/lib/jvm/bellsoft-java8-full-amd64
-
-    NOTE: You may need to log out and back in again after setting JAVA_HOME before the Autopsy
-          unix_setup.sh script can see the value.
-
--- OS X:
-    1. Install BellSoft Java 8.
-        % brew tap bell-sw/liberica
-        for macOS BigSur and later:
-             % brew install --cask liberica-jdk8-full
-        for macOS versions before BigSur:
-             % brew cask install liberica-jdk8-full
-    2. Set JAVA_HOME environment variable to location of JRE installation.
-       e.g. add the following to ~/.bashrc
-           export JAVA_HOME=$(/usr/libexec/java_home -v 1.8)
-
-- Confirm your version of Java by running
-  % java -version
-    openjdk version "1.8.0.232"
-    OpenJDK Runtime Environment (build 1.8.0_232-BellSoft-b10)
-    OpenJDK 64-Bit Server VM (build 25.232-b10, mixed mode)
-
-* Install The Sleuth Kit Java Bindings *
-
-Autopsy depends on a specific version of The Sleuth Kit.  You need the Java libraries of The Sleuth Kit installed, which is not part of all packages.
-
-- Linux: Install the sleuthkit-java.deb file that you can download from github.com/sleuthkit/sleuthkit/releases.  This will install libewf, etc. For example:
--- % sudo apt install ./sleuthkit-java_4.8.0-1_amd64.deb
-
-- OS X: Build The Sleuth Kit from source.
-    See https://slo-sleuth.github.io/tools/InstallingAutopsyOnMacOS.html for a comprehensive write-up
-    on building The Sleuth Kit and getting Autopsy to run on Mac OS.
-
-
-* Install Autopsy *
-
-- Extract the contents of the Autopsy ZIP file to a folder.
-- Open a terminal and cd into the Autopsy folder.
-- Run the unix_setup.sh script to configure Autopsy
-  % sh unix_setup.sh
-
-
-* Running Autopsy *
-
-- In a terminal, change to the ‘bin’ directory in the Autopsy folder.
-- Run Autopsy
-  % ./autopsy
-
-* Troubleshooting *
+* Troubleshooting *
 
 - If you see something like "Cannot create case: javafx/scene/paint/Color" it is an indication that Java FX
   is not being found.
diff --git a/unix_install_scripts/add_osx_jna.sh b/linux_macos_install_scripts/add_macos_jna.sh
similarity index 84%
rename from unix_install_scripts/add_osx_jna.sh
rename to linux_macos_install_scripts/add_macos_jna.sh
index 6d899902e1..f186de8f75 100644
--- a/unix_install_scripts/add_osx_jna.sh
+++ b/linux_macos_install_scripts/add_macos_jna.sh
@@ -2,7 +2,7 @@
 # Updates jna paths for mac
 
 usage() {
-    echo "Usage: add_osx_jna.sh [-i base_install_location (i.e. /home/usr/autopsy)] [-a application_name (default: autopsy)]" 1>&2
+    echo "Usage: add_macos_jna.sh [-i base_install_location (i.e. /home/usr/autopsy)] [-a application_name (default: autopsy)]" 1>&2
 }
 
 APPLICATION_NAME="autopsy"
diff --git a/unix_install_scripts/install_application_from_zip.sh b/linux_macos_install_scripts/install_application_from_zip.sh
similarity index 100%
rename from unix_install_scripts/install_application_from_zip.sh
rename to linux_macos_install_scripts/install_application_from_zip.sh
diff --git a/unix_install_scripts/install_prereqs_osx.sh b/linux_macos_install_scripts/install_prereqs_macos.sh
similarity index 100%
rename from unix_install_scripts/install_prereqs_osx.sh
rename to linux_macos_install_scripts/install_prereqs_macos.sh
diff --git a/unix_install_scripts/install_prereqs_ubuntu.sh b/linux_macos_install_scripts/install_prereqs_ubuntu.sh
similarity index 100%
rename from unix_install_scripts/install_prereqs_ubuntu.sh
rename to linux_macos_install_scripts/install_prereqs_ubuntu.sh
diff --git a/unix_install_scripts/install_tsk_from_src.sh b/linux_macos_install_scripts/install_tsk_from_src.sh
similarity index 100%
rename from unix_install_scripts/install_tsk_from_src.sh
rename to linux_macos_install_scripts/install_tsk_from_src.sh
-- 
GitLab