Skip to content

setupGuide.md

Latest commit

 

History

History
373 lines (244 loc) · 10.7 KB

setupGuide.md

File metadata and controls

373 lines (244 loc) · 10.7 KB

Ipmlab Setup Guide

Before trying to set up Ipmlab, check if the following requirements are met:

  • The installation platform is Linux-based (e.g. Unbuntu or Linux Mint).
  • Python 3.8 (or more recent) is installed on the target platform. Older 3.x versions may (but are not guaranteed to) work.

Getting Ipmlab up running requires a number of installation and configuration steps:

  1. Update the package index
  2. Add user to "disk" group
  3. Disable automatic mounting of removable media
  4. Install Tkinter if it is not installed already
  5. Install uv if it is not installed already
  6. Install Sleuthkit
  7. Install either ddrescue, or the Aaru Data Preservation Suite software (and configure it), or both (note: Aaru is not working as of yet!).
  8. Install Ipmlab
  9. Configure Ipmlab

Each step is described in detail below.

Update package index

As we'll be installing a few Debian packages, it's a good idea to first update the package index, to ensure the most recent versions of all packages are installed:

sudo apt update

Add user to disk group

For Linux, in order to have access to block devices as a non-root user, you must add your user name to the disk group. You can do this with the command below:

sudo adduser $USER disk

The user is now added to the 'disk' system group. Now log out, and then log in again for the changes to take effect.

Disable automatic mounting of removable media

In order to minimise any risks of accidental write actions to e.g. floppy disks that are processed with Ipmlab, it is strongly suggested to disable automatic mounting of removable media. The exact command depends on the Linux desktop you're using. For the MATE desktop use this:

gsettings set org.mate.media-handling automount false

For a GNOME desktop use this command:

gsettings set org.gnome.desktop.media-handling automount false

And for the Cinnamon desktop:

gsettings set org.cinnamon.desktop.media-handling automount-open false

You can use the below command to verify the automount setting (MATE):

gsettings get org.mate.media-handling automount

Or, for GNOME:

gsettings get org.gnome.desktop.media-handling automount

And finally for Cinnamon:

gsettings get org.cinnamon.desktop.media-handling automount-open

If all goes well, this will result in:

false

Please be aware that disabling the automount feature does not provide tamper-proof write blocking! It only works at the level of the operating system's default file manager, and it won't keep a user from manually mounting a device. Also, the gsettings command only works at the user level. This means that for someone who logs in with a different user name, the default automount setting applies (which means automount will be enabled).

If possible, use a forensic write blocker if more robust write-blocking is needed, but note that these devices may not always work as expected for USB adapter devices (such as USB 3.5" floppy drives).

Install Tkinter

You may need to install Tkinter, if it is not installed already. You can install it using the OS's package manager (there is no PyInstaller package for Tkinter). If you're using apt this should work:

sudo apt install python3-tk

Install uv

As of 2026, the recommended way to install Python-based tools uses uv tool. First, check if uv is already installed on your system by typing the uv command in a terminal:

uv

If this results in a help message, uv is installed. If not, install uv with the following command:

curl -LsSf https://astral.sh/uv/install.sh | sh

Alternatively, you can use wget if your system doesn't have curl installed:

wget -qO- https://astral.sh/uv/install.sh | sh

In some cases the installation script will update your system's configuration to make the location of the uv executable globally accessible. If this happens, just close your current terminal, and open a new one for these changes to take effect. Pay attention to the screen output of the installation script for any details on this.

Install Sleuthkit

We need Sleuthkit for extracting Dfxml metadata. To install, use:

sudo apt install sleuthkit

Install Ddrescue

Install ddrescue using this command:

sudo apt install gddrescue

Install Aaru

Not supported yet!

Install Ipmlab

Use the following command to install Ipmlab:

uv tool install ipmlab

Configuration

Before Ipmlab is ready for use you need to configure it. You can do this by running the followinng command:

ipmlab-configure

If this doesn't work, try again with the full path to the configuration script:

~/.local/bin/ipmlab-configure

The output should look something like this:

2026-01-29 18:38:09,542 - INFO - Scripts directory: /home/johan/.local/bin
2026-01-29 18:38:09,542 - INFO - Package directory: /home/johan/.local/share/uv/tools/ipmlab/lib/python3.12/site-packages/ipmlab
2026-01-29 18:38:09,542 - INFO - Home directory: /home/johan
2026-01-29 18:38:09,542 - INFO - Applications directory: /home/johan/.local/share/applications/
2026-01-29 18:38:09,542 - INFO - Configuration directory: /home/johan/.config/ipmlab
2026-01-29 18:38:09,542 - INFO - creating desktop file /home/johan/.local/share/applications/ipmlab.desktop
Ipmlab configuration completed successfully!

Editing the configuration file

The automatically generated configuration file needs some further manual editing, which is explained in the sections below.

Configuration file location

The configuration file is located at:

~/.config/ipmlab/config.xml

Configuration variables

Now open the configuration file config.xml in a text editor, or, alternatively, use a dedicated XML editor. Carefully go through all the variables (which are defined as XML elements), and modify them if necessary. Here is an explanation of all variables.

inDevice

This defines the path to the device you want to use for imaging. You need to use a device path such as:

<inDevice>/dev/sdd</inDevice>

If you're not sure about the device path to use, do this:

  1. Make sure the floppy drive is connected to your machine, with a floppy inserted.
  2. Then issue the following command to get info about all available storage devices:
sudo lshw -short -class disk

Example output:

H/W path       Device     Class          Description
====================================================
/0/13/0.0.0    /dev/sda   disk           1TB TOSHIBA DT01ACA1
/0/14/0.0.0    /dev/sdb   disk           250GB WDC WDS250G2B0A
/0/15/0.0.0    /dev/sdc   disk           5TB Expansion HDD
/0/16/0.0.0    /dev/sdd   disk           1474KB USB-FDU

In the list of output devices, look for a device with a small (typically 1474 or 737 KB) storage capacity. In the example above /dev/sdd is the floppy drive.

rootDir

This defines the root directory where Ipmlab will write its data. Ipmlab output is organised into batches, and each batch is written to rootDir. Make sure to pick an existing directory with plenty of space.

Example:

<rootDir>/home/johan/test/ipmlab-test</rootDir>

prefixBatch

This is a text prefix that is added to the automatically-generated batch names:

<prefixBatch>kb</prefixBatch>

socketHost

Defines the host address that is used if the socket API is enabled (see below). Use 127.0.0.1 for localhost:

<socketHost>127.0.0.1</socketHost>

socketPort

Defines the port that is used if the socket API is enabled (see below):

<socketPort>65432</socketPort>

enablePPNLookup

Flag that controls whether PPN lookup is enabled. If set to True, the Ipmlab interface contains a widget for entering a PPN identifier. After submitting, Ipmlab then performs a lookup on the PPN in the KB catalogue, and automatically extracts the title of the corresponding entry (which is then added to the batch manifest). If set to False, the Ipmlab interface contains a widget in which an operator can manually enter a Title string; the entered value is written to the batch manifest. In this case no PPN lookup is performed, and the PPN-value in the batch manifest will be a zero-length string.

Allowed values:

<enablePPNLookup>True</enablePPNLookup>

and:

<enablePPNLookup>False</enablePPNLookup>

enableSocketAPI

This is a flag that -if set to True- enables Ipmlab to pick up Title and PPN info from a client application through a socket interface (disabled by default):

<enableSocketAPI>False</enableSocketAPI>

fiwalkBin

This points to the location of Fiwalk binary:

<fiwalkBin>/usr/bin/fiwalk</fiwalkBin>

imagingApplication

This sets the application that is used for imaging. Allowed values are "aaru" and "ddrescue":

<imagingApplication>ddrescue</imagingApplication>

aaruBin

This points to the location of Aaru binary:

<aaruBin>/usr/bin/aaru</aaruBin>

ddrescueBin

This points to the location of ddrescue binary:

<ddrescueBin>/usr/bin/ddrescue</ddrescueBin>

blockSize

This defines the block size used by ddrescue:

<blockSize>512</blockSize>

retries

This sets the maximum number of times ddrescue will try to read an unreadable sector:

<retries>4</retries>