torrent/README.md

  <h1>Torrent Mover v8.0</h1>
  
  <div class="section">
    <h2>Description</h2>
    <p>
      <strong>Torrent Mover</strong> is a Bash script designed to automate the processing of completed torrents in Transmission.
      It moves or copies downloaded files from a Transmission‑reported download location to designated destination directories on your system.
      This enhanced version includes robust locking, advanced error handling, parallel processing, configurable path mapping, improved archive extraction,
      and optional file integrity verification.
    </p>
  </div>
  
  <div class="section">
    <h2>Features</h2>
    <ul>
      <li><strong>Automatic Torrent Processing:</strong> Monitors Transmission for completed torrents and processes them based on configurable seeding criteria.</li>
      <li><strong>Configurable Path Mapping:</strong> Uses Transmission’s reported download path (e.g. <code>/downloads</code>) and maps it to your local file system (e.g. <code>/mnt/dsnas2</code>) via configurable settings.</li>
      <li><strong>Robust Locking:</strong> Employs <code>flock</code> to ensure that only one instance of the script runs at a time.</li>
      <li><strong>Advanced Error Handling & Logging:</strong> Global error handler and detailed logging (with DEBUG mode support). Optionally, logs to syslog.</li>
      <li><strong>Parallel File Operations:</strong> Utilizes GNU Parallel for moving, copying, and generating checksums, enabling efficient multi-threaded processing.</li>
      <li><strong>Archive Extraction:</strong> Extracts archives (RAR, ZIP, 7z) into subdirectories at the destination—preserving internal structure—while retaining the archive in the source until seeding criteria are met.</li>
      <li><strong>Directory Deduplication:</strong> Prevents re‑processing the same source directory if multiple torrents reference it.</li>
      <li><strong>Optional Integrity Verification:</strong> Verifies file integrity by comparing MD5 checksums after transfer.</li>
    </ul>
  </div>
  
  <div class="section">
    <h2>Requirements</h2>
    <ul>
      <li>Bash</li>
      <li>transmission-remote</li>
      <li>GNU Parallel</li>
      <li>unrar, unzip, 7z</li>
      <li>bc</li>
    </ul>
  </div>
  
  <div class="section">
    <h2>Installation</h2>
    <ol>
      <li><strong>Download the Script:</strong> Save the script (e.g., <code>torrent-mover.sh</code>) to your desired location (e.g., <code>/usr/local/bin/</code>).</li>
      <li><strong>Make It Executable:</strong>
        <pre>chmod +x /usr/local/bin/torrent-mover.sh</pre>
      </li>
      <li><strong>Create/Edit the Configuration File:</strong> The script expects a configuration file at <code>/etc/torrent/mover.conf</code>. See the configuration section below.</li>
    </ol>
  </div>
  
  <div class="section">
    <h2>Configuration</h2>
    <p>Edit or create <code>/etc/torrent/mover.conf</code> with the following content:</p>
    <pre>
# Transmission settings
TRANSMISSION_IP="192.168.1.100"         # Replace with your Transmission server's IP
TRANSMISSION_PORT="9091"                # Replace with your Transmission server's port
TRANSMISSION_USER="your_username"       # Transmission username (if set)
TRANSMISSION_PASSWORD="your_password"   # Transmission password (if set)

# Path mapping settings
TRANSMISSION_PATH_PREFIX="/downloads"
LOCAL_PATH_PREFIX="/mnt/dsnas2"

# Destination directories
DIR_GAMES_DST="/mnt/dsnas1/Games"
DIR_APPS_DST="/mnt/dsnas1/Apps"
DIR_MOVIES_DST="/mnt/dsnas1/Movies"
DIR_BOOKS_DST="/mnt/dsnas1/Books"
DEFAULT_DST="/mnt/dsnas1/Other"

# Additional storage directories (comma-separated list)
STORAGE_DIRS="/mnt/dsnas/Movies"

# Performance settings
PARALLEL_THREADS="32"
PARALLEL_PROCESSING=1

# Operation mode: "move" or "copy"
COPY_MODE="copy"

# File tracking & integrity
PROCESSED_LOG="/var/log/torrent_processed.log"
CHECKSUM_DB="/var/lib/torrent/checksums.db"

# Logging settings
LOG_FILE="/var/log/torrent_mover.log"
LOG_LEVEL="INFO"          # Set to "DEBUG" for more verbose logging
USE_SYSLOG="false"        # Set to "true" to log messages to syslog

# Optional integrity verification after transfer ("true" to enable)
CHECK_TRANSFER_INTEGRITY="true"
    </pre>
  </div>
  
  <div class="section">
    <h2>Usage</h2>
    <p>Run the script using the following options:</p>
    <ul>
      <li><strong>Dry-run mode (simulate operations):</strong>
        <pre>/usr/local/bin/torrent-mover.sh --dry-run</pre>
      </li>
      <li><strong>Interactive mode (prompt for confirmation):</strong>
        <pre>/usr/local/bin/torrent-mover.sh --interactive</pre>
      </li>
      <li><strong>Cache warmup mode (pre-calculate checksums):</strong>
        <pre>/usr/local/bin/torrent-mover.sh --cache-warmup</pre>
      </li>
      <li><strong>Debug mode (verbose logging):</strong>
        <pre>/usr/local/bin/torrent-mover.sh --debug</pre>
      </li>
    </ul>
    <p>You can combine options as needed. For example:</p>
    <pre>/usr/local/bin/torrent-mover.sh --dry-run --debug</pre>
  </div>
  
  <div class="section">
    <h2>How It Works</h2>
    <ol>
      <li><strong>Locking:</strong> Uses <code>flock</code> to ensure only one instance runs at a time.</li>
      <li><strong>Path Translation:</strong> The script translates the Transmission-reported path (e.g., <code>/downloads</code>) to the local file system path (e.g., <code>/mnt/dsnas2</code>) using the configured mapping.</li>
      <li><strong>Torrent Processing:</strong> Retrieves torrent info via <code>transmission-remote</code> and processes torrents that are 100% complete. It skips torrents already processed or those with duplicate source directories.</li>
      <li><strong>File Verification & Deduplication:</strong> Compares file checksums between source and destination, and avoids re‑processing if a match is found.</li>
      <li><strong>Archive Extraction:</strong> Extracts archives (RAR, ZIP, 7z) into subdirectories within the destination while preserving directory structure. The original archive is retained in the source until seeding criteria are met.</li>
      <li><strong>Seeding Criteria:</strong> Checks seeding ratio and time. When thresholds are met, the torrent is removed from Transmission.</li>
      <li><strong>Integrity Check (Optional):</strong> Optionally verifies file integrity by comparing MD5 checksums post-transfer.</li>
    </ol>
  </div>
  

  
  <div class="section">
    <h2>License</h2>
    <p>
      This script is provided as-is without any warranty. Use it at your own risk. Contributions and improvements are welcome.
    </p>
  </div>
</body>