jdiskwipe - Detailed Usage Guide

Quick Start
Command-Line Reference
Usage Scenarios
Safety Checklist
Performance Tuning
Troubleshooting
Advanced Topics

Quick Start

Minimal Example

# Build the project
mvn clean package

# Wipe a directory (interactive mode with confirmation)
java -jar target/jdiskwipe-1.0.jar /tmp/secure-wipe

The tool will prompt for confirmation before proceeding.

Non-Interactive Example

# Skip confirmation prompt (for scripts)
java -jar target/jdiskwipe-1.0.jar -y /tmp/secure-wipe

Command-Line Reference

Synopsis

java -jar jdiskwipe-1.0.jar [OPTIONS] DIRECTORY [DIRECTORY2 ...]

Options

Option	Long Form	Argument	Default	Description
`-t`	`--threads`	`<count>`	4	Number of worker threads
`-b`	`--buffer-size`	`<bytes>`	10485760	Buffer size in bytes (10MB)
`-y`	`--yes`	-	false	Skip confirmation prompt
`-h`	`--help`	-	-	Display help and exit

Arguments

DIRECTORY: One or more directory paths to wipe
- Can be relative or absolute paths
- Directories will be created if they don't exist
- Multiple directories can be specified

Exit Codes

Code	Meaning
0	Success (operation completed or help displayed)
1	Error (invalid arguments, unsafe directory, or runtime failure)

Usage Scenarios

Scenario 1: Preparing a USB Drive for Sale

Before selling or giving away a USB drive, wipe its free space:

# Mount the drive (example: /media/usb)
# Delete any files you want to remove
# Then wipe free space

java -jar jdiskwipe-1.0.jar /media/usb/wipe-temp

Steps:

Mount the drive
Delete sensitive files normally
Create a temporary directory on the drive
Run jdiskwipe on that directory
After completion, delete the wipe directory
Unmount and remove the drive

Scenario 2: Decommissioning a Server Disk

Securely wipe free space on a disk before decommissioning:

# Create a wipe directory
mkdir -p /mnt/old-disk/secure-wipe

# Run with more threads for faster completion
java -jar jdiskwipe-1.0.jar -t 16 -b 52428800 /mnt/old-disk/secure-wipe

# After completion, the disk can be safely removed

Notes:

Use more threads (-t 16) for server-class hardware
Increase buffer size (-b 52428800 = 50MB) for better performance
Monitor system resources during operation

Scenario 3: Automated Cleanup Script

Integrate jdiskwipe into a cleanup script:

#!/bin/bash
set -e

# Configuration
WIPE_DIR="/tmp/secure-wipe-$$"
THREADS=8
BUFFER_SIZE=20971520  # 20MB

# Create temporary wipe directory
mkdir -p "$WIPE_DIR"

# Run jdiskwipe with auto-confirm
java -jar /path/to/jdiskwipe-1.0.jar \
    -y \
    -t "$THREADS" \
    -b "$BUFFER_SIZE" \
    "$WIPE_DIR"

# Cleanup
rm -rf "$WIPE_DIR"

echo "Secure wipe completed successfully"

Scenario 4: Wiping Multiple Partitions

Wipe free space on multiple partitions simultaneously:

java -jar jdiskwipe-1.0.jar \
    /mnt/partition1/wipe \
    /mnt/partition2/wipe \
    /mnt/partition3/wipe

Benefits:

Process multiple directories in sequence
Single confirmation for all operations
Consistent configuration across all targets

Scenario 5: Low-Resource Systems

For systems with limited memory or CPU:

# Use fewer threads and smaller buffer
java -jar jdiskwipe-1.0.jar -t 1 -b 1048576 /tmp/wipe

Configuration:

Single thread (-t 1) for minimal CPU usage
1MB buffer (-b 1048576) for low memory usage
Slower but safe for resource-constrained systems

Safety Checklist

Before running jdiskwipe, verify:

Backup critical data - Ensure all important data is backed up elsewhere
Verify target directory - Double-check you're targeting the correct path
Check available space - Ensure the disk has free space to fill
System resources - Ensure sufficient CPU and memory for operation
No active processes - Verify no critical processes are using the disk
Sufficient time - Operation may take hours for large disks
Monitoring capability - Ensure you can monitor progress if needed

Pre-Flight Verification

# 1. Check target directory
ls -la /target/directory

# 2. Check available space
df -h /target/directory

# 3. Check system resources
free -h
top

# 4. Verify directory is writable
touch /target/directory/test && rm /target/directory/test

Post-Operation Verification

# 1. Check disk is actually full
df -h /target/directory

# 2. Verify wipe files were created
ls -lh /target/directory/wipe*

# 3. Cleanup wipe files
rm /target/directory/wipe*

# 4. Verify free space is restored
df -h /target/directory

Performance Tuning

Determining Optimal Thread Count

Your optimal thread count depends on several factors:

CPU cores:

# Check CPU core count
nproc

Recommendations:

Single disk (HDD): 2-4 threads (disk I/O is bottleneck)
Single disk (SSD): 4-8 threads (faster I/O allows more threads)
RAID array: 8-16 threads (multiple disks benefit from parallelism)
Network storage: 2-4 threads (network latency is bottleneck)

Testing:

# Try different thread counts and time the operation
time java -jar jdiskwipe-1.0.jar -y -t 4 /tmp/test-wipe-4
time java -jar jdiskwipe-1.0.jar -y -t 8 /tmp/test-wipe-8

Determining Optimal Buffer Size

Memory considerations:

Total buffer memory = threads × buffer_size
Example: 8 threads × 20MB = 160MB RAM

I/O considerations:

HDD: 10-50MB buffers reduce seek overhead
SSD: 1-20MB buffers sufficient (minimal seek time)
Network: Larger buffers (50-100MB) reduce round trips

Recommendations:

Default: 10MB (10485760) - good for most cases
Low memory: 1MB (1048576) - minimal RAM usage
High performance: 50MB (52428800) - fewer system calls
Very low memory: 512KB (524288) - absolute minimum

Monitoring Performance

During operation, monitor:

# Monitor disk I/O
iostat -x 2

# Monitor CPU usage
top

# Monitor memory usage
free -h

# Monitor disk space
watch -n 5 'df -h /target/directory'

Troubleshooting

Problem: "SAFETY VIOLATION: Cannot wipe system directory"

Cause: Attempting to wipe a protected system directory.

Solution: Verify your target path. The tool blocks:

/, /bin, /etc, /usr, /var, /home
Create a subdirectory in a safe location instead

# Wrong: java -jar jdiskwipe.jar /home
# Right: java -jar jdiskwipe.jar /home/user/temp-wipe

Problem: "Parent directory is not writable"

Cause: Insufficient permissions to create the target directory.

Solutions:

Use a directory you have write access to
Run with appropriate permissions (NOT recommended for root directories)
Change directory ownership

# Check permissions
ls -ld /parent/directory

# Fix permissions (if appropriate)
chmod u+w /parent/directory

Problem: Operation is very slow

Possible causes:

Disk is nearly full (normal - takes time to fill remaining space)
Too many threads for disk type
Buffer size too small
Disk is failing/slow

Solutions:

# Check disk health
smartctl -a /dev/sdX

# Reduce threads for HDD
java -jar jdiskwipe.jar -t 2 /target

# Increase buffer size
java -jar jdiskwipe.jar -b 52428800 /target

Problem: Out of memory error

Cause: Too many threads or too large buffer size.

Solution: Reduce total memory usage:

# Calculate: threads × buffer_size = total memory
# Example: 4 × 10MB = 40MB (safe)
# Example: 16 × 100MB = 1.6GB (may be too much)

# Reduce threads
java -jar jdiskwipe.jar -t 2 /target

# Or reduce buffer size
java -jar jdiskwipe.jar -b 5242880 /target  # 5MB

Problem: Process interrupted/killed

Causes:

User interrupted with Ctrl+C
System killed process (OOM killer)
System shutdown/reboot

Impact:

Partial wipe files remain on disk
Free space is partially filled
Operation is safe to restart

Cleanup:

# Remove partial wipe files
rm /target/directory/wipe*

# Restart operation
java -jar jdiskwipe.jar /target/directory

Problem: Disk not completely full after operation

Causes:

Reserved space (filesystem reserves 5% typically)
Small remaining fragments
Metadata overhead

Verification:

# Check actual free space
df -h /target

# If significant space remains, run again
java -jar jdiskwipe.jar -y /target/wipe2

Advanced Topics

Integration with Secure Erase

For maximum security, combine jdiskwipe with hardware-level secure erase:

# 1. Wipe free space with jdiskwipe
java -jar jdiskwipe.jar -y /mnt/disk/wipe

# 2. Then use ATA Secure Erase (if supported)
hdparm --user-master u --security-set-pass password /dev/sdX
hdparm --user-master u --security-erase password /dev/sdX

Multi-Pass Wiping

For paranoid security, run multiple passes:

#!/bin/bash
# 3-pass wipe script

for pass in 1 2 3; do
    echo "Pass $pass of 3..."
    java -jar jdiskwipe.jar -y /tmp/wipe-pass-$pass
    rm -rf /tmp/wipe-pass-$pass
done

echo "Multi-pass wipe complete"

Verifying Wipe Effectiveness

Use forensic tools to verify data is unrecoverable:

# Use photorec to scan for recoverable files
photorec /dev/sdX

# Use foremost for file carving
foremost -i /dev/sdX -o recovery-test

Customizing the JAR

Build a custom JAR with different defaults:

# Edit WipeConfiguration.java defaults
# Then rebuild
mvn clean package

# Or use environment variables/system properties (future enhancement)

Logging Output

Capture operation log:

# Log to file
java -jar jdiskwipe.jar /target 2>&1 | tee wipe-operation.log

# Log with timestamps
java -jar jdiskwipe.jar /target 2>&1 | while read line; do
    echo "$(date -Iseconds) $line"
done | tee wipe-operation.log

Best Practices

Always backup first - Verify backups before wiping
Test on small volumes - Understand behavior before large operations
Monitor first run - Watch resource usage and adjust accordingly
Use appropriate threads - More isn't always better
Clean up after - Remove wipe files after operation
Verify completion - Check disk is actually full
Document configuration - Record settings that work for your environment
Schedule appropriately - Run during off-hours for servers
Plan for time - Large disks take hours or days
Have fallback - Know how to stop and restart if needed

Getting Help

Read error messages carefully - They contain specific guidance
Check this document - Most issues are covered here
Review README - Basic usage and safety information
Check GitHub issues - Someone may have had the same problem
Open an issue - Provide system details and error messages

FilesExpand file tree

USAGE.md

Latest commit

History