How to Configure IPED: A Complete Guide to Forensic Processing Profiles

IPED uses a layered configuration hierarchy where settings from global defaults, LocalConfig.txt, case-specific IPEDConfig.txt, and command-line overrides merge at runtime via the Configuration class.

IPED (Indexador e Processador de Evidências Digitais) is an open-source forensic tool designed for processing large volumes of digital evidence. Learning how to configure IPED properly allows you to optimize processing performance, enable specific modules like hash databases or OCR, and adapt the tool to specialized forensic workflows. The configuration system is implemented in iped-engine/src/main/java/iped/engine/config/Configuration.java and follows a strict precedence-based architecture.

Understanding IPED's Layered Configuration Hierarchy

The Configuration class loads settings at startup by merging multiple sources in a specific order. Lower layers provide defaults, while higher layers override previous values.

Configuration Precedence Order

IPED applies settings from the following layers (lowest to highest priority):

1. Global defaults – Hard-coded values within the Java codebase, primarily in Configuration.java
2. Local environment – Machine-specific settings in iped-app/resources/config/LocalConfig.txt (locale, temp folders, plugin directories)
3. Application config – Main user-editable file at <case>/conf/IPEDConfig.txt that toggles features like carving and OCR
4. Profile config – Pre-defined use-case profiles (forensic, pedo, fastmode, blind, triage) stored in iped-app/resources/config/profiles/<profile>/IPEDConfig.txt
5. Profile-specific parsers and carvers – XML configurations in profiles/<profile>/conf/ParserConfig.xml and CarverConfig.xml
6. Command-line overrides – Runtime flags like -profile and -Xkey=value parsed by CmdLineArgsImpl
7. Runtime plugins – JAR files placed in the pluginFolder directory defined in LocalConfig.txt

When the application initializes, Configuration.loadConfigurables() (lines 61–84) constructs a ConfigurationDirectory, adds the default and profile-specific paths, and instantiates a ConfigurationManager to parse all *.properties and *.xml files.

Key Configuration Classes

Three primary classes manage IPED configuration:

• Configuration – Central singleton that resolves the configuration directory hierarchy and loads all configurables
• ConfigurationManager – Reads files added to the ConfigurationDirectory and injects properties into corresponding Configurable objects
• CmdLineArgsImpl (iped-app/src/main/java/iped/app/processing/CmdLineArgsImpl.java) – Parses command-line options and sets system properties that influence configuration loading

Step-by-Step IPED Configuration

1. Create a Case Folder Structure

Every IPED case requires a specific directory layout. Create a folder with a conf subdirectory to hold your main configuration:

my_case/
├── conf/
│   └── IPEDConfig.txt        ← Copy from default template
└── iped/                     ← Generated at runtime

IPED treats the conf/ directory as the configuration path and expects to find IPEDConfig.txt there.

2. Edit IPEDConfig.txt for Case-Specific Settings

The IPEDConfig.txt file uses simple key = value syntax parsed by UTF8Properties. Copy the template from iped-app/resources/config/profiles/forensic/IPEDConfig.txt and modify values to enable required modules:

# Processing Settings

enableHashDBLookup = true
enableQRCode = true
enableCarving = true
enableImageSimilarity = true
enableOCR = false

Place this file at <case>/conf/IPEDConfig.txt. Settings here override global defaults but yield to profile configurations and command-line arguments.

3. Configure Local Environment in LocalConfig.txt

Machine-specific parameters belong in iped-app/resources/config/LocalConfig.txt. These values are read early during initialization (see Configuration.getConfiguration() lines 95–106):

locale = en
indexTemp = /tmp/iped-temp
indexTempOnSSD = true
outputOnSSD = false
numThreads = 8
pluginFolder = ../plugins/

Adjust numThreads based on your CPU cores, and set indexTemp to a fast SSD path for better indexing performance.

4. Select a Processing Profile

IPED ships with pre-configured profiles optimized for different forensic scenarios:

• forensic – General-purpose deep processing
• pedo – Child abuse investigations with specific hash sets
• fastmode – Quick triage with reduced parsing depth
• blind – Processing without external lookup services
• triage – Rapid preliminary analysis

Invoke a profile using the -profile flag:

java -jar iped.jar -d evidence.E01 -profile forensic

The profile loads its own IPEDConfig.txt from iped-app/resources/config/profiles/forensic/, along with specific parser definitions (ParserConfig.xml) and carving rules (CarverConfig.xml). Profile selection is handled by CmdLineArgsImpl at line 93.

5. Override Settings via Command Line

Override any configuration property without editing files using the -X prefix. These parameters are stored in extraParams (see CmdLineArgsImpl lines 34–36) and injected as system properties:

java -jar iped.jar -d disk.E01 -XenableOCR=true -XocrLang=eng,por

This approach is useful for scripting and temporary adjustments. Command-line values take precedence over all file-based configurations.

6. Add Custom Plugins

Extend IPED functionality by placing JAR files in the directory specified by pluginFolder (default ../plugins/). During Configuration.loadConfigurables(), the method addPluginJarsToConfigurationLookup() (lines 42–57) automatically adds these JARs to the classpath and configuration lookup path.

Configuration Code Examples

Minimal IPEDConfig.txt Template

Create this file at my_case/conf/IPEDConfig.txt for basic forensic processing:

# conf/IPEDConfig.txt

enableHashDBLookup = true
enableCarving = true
enableOCR = false        # Disable OCR unless specifically needed

enableImageSimilarity = true
enableQRCode = true

Combining Profiles with Runtime Overrides

This example loads the pedo profile but forces OCR enablement via command line:

java -jar iped.jar \
   -d /evidence/disk.E01 \
   -profile pedo \
   -XenableOCR=true \
   -XocrLang=eng,por

The -profile pedo argument loads iped-app/resources/config/profiles/pedo/IPEDConfig.txt, while -XenableOCR=true overrides the profile's default OCR setting.

Adding a Custom Parser via XML

Create a new parser configuration at iped-app/resources/config/profiles/forensic/conf/myparser.xml:

<?xml version="1.0" encoding="UTF-8"?>
<properties>
    <parsers>
        <parser class="my.package.CustomParser">
            <params>
                <param name="processAll" type="bool">true</param>
            </params>
        </parser>
    </parsers>
</properties>

The ConfigurationManager automatically loads this XML because the profile's conf folder is added to the ConfigurationDirectory at startup.

Summary

• IPED configuration follows a layered hierarchy with seven precedence levels, from hard-coded defaults to command-line overrides.
• Case-specific settings belong in <case>/conf/IPEDConfig.txt, while machine-specific settings reside in iped-app/resources/config/LocalConfig.txt.
• Processing profiles (forensic, pedo, fastmode, etc.) provide pre-configured environments stored in iped-app/resources/config/profiles/.
• The Configuration class (iped-engine/src/main/java/iped/engine/config/Configuration.java) orchestrates loading via loadConfigurables(), while CmdLineArgsImpl handles runtime parameter injection.
• Use -Xkey=value syntax to override any property without modifying configuration files.
• Place custom JAR plugins in the directory defined by pluginFolder in LocalConfig.txt to extend functionality at runtime.

Frequently Asked Questions

What is the difference between LocalConfig.txt and IPEDConfig.txt?

LocalConfig.txt contains machine-specific settings like temp directory paths, thread counts, and plugin folders that apply to all cases processed on that workstation. IPEDConfig.txt resides in individual case folders and controls processing modules (hash lookup, carving, OCR) specific to that investigation. The Configuration class loads LocalConfig.txt first, then applies case-specific overrides from IPEDConfig.txt.

How do I resume an interrupted IPED processing job?

Use the --continue flag when invoking IPED from the command line. This tells the Configuration class to skip already processed items and resume from the last checkpoint. If you need to append new evidence to an existing case without reprocessing existing data, use the --append flag instead.

Can I create a custom processing profile?

Yes. Create a new directory under iped-app/resources/config/profiles/ (for example, myprofile/) and include an IPEDConfig.txt file along with optional conf/ParserConfig.xml and conf/CarverConfig.xml files. Invoke your custom profile with java -jar iped.jar -d evidence.E01 -profile myprofile. The profile system merges your custom settings with the global defaults according to the standard hierarchy.

Which configuration layer has the highest priority?

Command-line overrides using the -X prefix have the highest priority, followed by runtime plugin JARs, profile configurations, and case-specific IPEDConfig.txt settings. This precedence ensures that temporary runtime adjustments always take effect, while global defaults provide fallback values. The CmdLineArgsImpl class stores these overrides in extraParams and injects them as system properties that supersede file-based configurations.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}