Expanding the Disk on a FileWave Appliance - Debian

Overview

This guide explains how to use the FileWave Smart Disk Expansion script to automatically expand disk space on FileWave appliances. The script handles all the complexity of expanding LVM physical volumes, partitions, and filesystems with comprehensive logging and safety features.

What This Script Does

The script performs the following operations:

• Detects your appliance's LVM configuration automatically
• Expands physical volume (PV) backing devices
• Grows partitions using cloud-guest-utils (growpart)
• Extends the root logical volume (LV) to consume available space
• Grows the root filesystem online (supports ext4, ext3, ext2, and XFS)
• Repairs GPT partition tables if needed
• Logs all actions for troubleshooting and support cases

Prerequisites

• Root access (via sudo)
• Debian-based appliance (e.g., Debian 12/13)
• Disk already expanded at the hypervisor/storage level (this script only expands the OS partitions and filesystem)
• Network access (for automatic package installation, if needed)

The script automatically installs required tools if missing:

• cloud-guest-utils (growpart)
• lvm2 (LVM tools)
• util-linux (disk utilities)
• gdisk (GPT utilities)
• e2fsprogs (ext filesystem tools)
• xfsprogs (XFS filesystem tools)

Step-by-Step Instructions

Step 1: Download the Script

Open a terminal on your FileWave appliance and download the script:

cd /tmp
wget https://kb.filewave.com/attachments/485 -O filewave-expand-disk.sh
chmod +x filewave-expand-disk.sh

Alternatively, if wget is not available, use curl:

cd /tmp
curl -o filewave-expand-disk.sh https://kb.filewave.com/attachments/485
chmod +x filewave-expand-disk.sh

Step 2: Review the Script (Optional but Recommended)

Before running any system-modifying script, it's good practice to review it:

head -50 filewave-expand-disk.sh

This displays the first 50 lines, including the description and safety information.

Step 3: Test with Dry-Run (Strongly Recommended)

Always test the script in dry-run mode first to see what actions it would take:

sudo ./filewave-expand-disk.sh --dry-run

Expected output:

• Detects root LVM configuration (VG, LV, filesystem type)
• Lists PV devices backing the root LV
• Shows BEFORE state (VG free space, LV size, filesystem size)
• Lists actions it WOULD take (but doesn't execute them)
• Shows AFTER state (projected)

Example output snippet:

== Detecting root LVM layout ==
Root LV: /dev/vg0/root
VG:      vg0
FS type: ext4

== Finding PV backing the root LV ==
PV(s):   /dev/vda1

== BEFORE state ==
VG free:      10.0G
LV size:      50.0G
FS size (/):  50.0G
FS avail (/): 45.0G

== Expanding PV(s) and partition(s) (if needed) ==
Processing: /dev/vda1
  - would run: growpart /dev/vda /dev/vda1
  - pvresize /dev/vda1

DRY_RUN: command not executed

Review the dry-run output carefully:

• ✅ Are the device names correct?
• ✅ Is the VG/LV configuration what you expect?
• ✅ Does the projected growth make sense?

Step 4: Run the Script

Once you're confident with the dry-run, run the script for real:

sudo ./filewave-expand-disk.sh

The script will:

1. Install any missing prerequisite packages
2. Detect your LVM configuration
3. Expand PV/partitions if needed
4. Extend the LV
5. Grow the filesystem online
6. Create a support log in /var/log/filewave-expand-disk-YYYYMMDD-HHMMSS.log

Expected output:

Log file: /var/log/filewave-expand-disk-20260127-094500.log
If opening a support case, attach: /var/log/filewave-expand-disk-20260127-094500.log

== Checking and installing prerequisites ==
...

== Detecting root LVM layout ==
Root LV: /dev/vg0/root
VG:      vg0
FS type: ext4

...

== AFTER state ==
VG free:      0B
LV size:      60.0G
FS size (/):  60.0G
FS avail (/): 55.0G

SUMMARY: Expansion performed. LV grew by 10.0G and filesystem grew by 10.0G.

Support log file: /var/log/filewave-expand-disk-20260127-094500.log
Reboot not requested (default). No reboot will be performed.

Step 5: Verify the Expansion

Check that the filesystem was expanded:

df -h /

You should see the new size reflected in the "Size" column.

Example:

Filesystem      Size  Used Avail Use% Mounted on
/dev/mapper/vg0-root   60G  5.0G   55G   9% /

Compare this to the BEFORE state in the log.

Step 6: Reboot (If Recommended)

In most cases, no reboot is needed. However, the script may recommend a reboot if:

• GPT partition table repairs were necessary
• Kernel partition table cache needs refresh

If the script recommends a reboot:

sudo reboot

The appliance will restart. FileWave services typically auto-start on boot.

Usage Options

The script supports several command-line options:

Verbose Mode

Show detailed command output in the terminal (in addition to logging):

sudo ./filewave-expand-disk.sh --verbose

Use this for troubleshooting or when you want to see detailed progress.

Reboot Option

Automatically reboot at the end:

sudo ./filewave-expand-disk.sh --reboot

This is useful for automation or when you want to ensure partition table changes are fully applied.

Combined Options

sudo ./filewave-expand-disk.sh --dry-run --verbose
sudo ./filewave-expand-disk.sh --reboot --verbose

Support Log

The script creates a detailed support log in /var/log/:

Log location: /var/log/filewave-expand-disk-YYYYMMDD-HHMMSS.log

Why it's important:

• Contains all commands executed
• Includes BEFORE/AFTER metrics
• Helps FileWave Support diagnose issues
• Is automatically world-readable for easy sharing

To view the log:

cat /var/log/filewave-expand-disk-*.log

When opening a support case:

• Attach the support log: filewave-expand-disk-YYYYMMDD-HHMMSS.log
• Include the BEFORE/AFTER sizes
• Note any warnings or errors from the script

Troubleshooting

"ERROR: This script must be run as root"

Solution: Use sudo:

sudo ./filewave-expand-disk.sh

"ERROR: Root filesystem is not an LVM logical volume"

Cause: Your appliance does not use LVM storage layout.

Solution: This script only works with LVM-based appliances. Contact FileWave Support for non-LVM systems.

"WARN: Unsupported/unknown filesystem type"

Cause: The root filesystem is an uncommon type (not ext4, ext3, ext2, or XFS).

Solution: Contact FileWave Support with the support log.

Filesystem didn't grow (AFTER state shows same size as BEFORE)

Possible causes:

1. VG has no free space: If VG free is 0 bytes in BEFORE state, there's nothing to expand. Verify the disk was actually expanded at the hypervisor level.
2. Partition didn't grow: Check the support log for growpart output. This typically means the underlying disk wasn't resized at the storage layer.
3. No-op short-circuit triggered: The script detected the disk was already fully expanded.

Solution: Check the support log for details. If still unsure, contact FileWave Support.

"Device or resource busy" warnings

Cause: The system is actively using the disk (expected on live systems).

Solution: These warnings are normal and safe to ignore. The script continues and typically succeeds anyway.

Common Scenarios

Scenario 1: Expand 50GB Appliance to 100GB

1. At hypervisor level: Resize the virtual disk from 50GB to 100GB
2. On appliance: Run dry-run to verify
3. On appliance: Run the script
4. Verify: Check with df -h /

# Dry-run
sudo ./filewave-expand-disk.sh --dry-run

# Real run
sudo ./filewave-expand-disk.sh

# Verify
df -h /

Scenario 2: Expand with Verbose Output for Troubleshooting

sudo ./filewave-expand-disk.sh --verbose 2>&1 | tee ~/expansion.log

This captures all output to both terminal and a file for review.

Scenario 3: Expand and Reboot Automatically

sudo ./filewave-expand-disk.sh --reboot

Useful for scheduled maintenance windows.

FAQ

Q: Will this downtime affect FileWave services?
A: No. The filesystem is expanded online with no downtime. Services continue running but you may be advised to reboot.

Q: Do I need to stop FileWave services?
A: No. The script works while services are running.

Q: What filesystems are supported?
A: ext4, ext3, ext2, and XFS. Others may work but are not officially tested.

Q: Can I run this script multiple times?
A: Yes. It's safe to run multiple times. It will detect if space was already expanded and skip unnecessary operations.

Q: Do I need to reboot after running this?
A: Usually not. Reboot is only recommended if partition table repairs were necessary (the script will tell you).

Q: How long does the expansion take?
A: Typically 1-5 minutes depending on appliance size and system load.

Q: Is the script reversible?
A: No. Once expanded, you cannot shrink the filesystem or LV. Plan accordingly.

Support

If you encounter issues or have questions:

1. Review the support log: /var/log/filewave-expand-disk-YYYYMMDD-HHMMSS.log
2. Run with --verbose to see detailed output
3. Contact FileWave Support with:
   • The support log attached
   • Description of the issue
   • Output from df -h /, lvs, vgs, pvs