Skip to main content

Expanding the Disk on a FileWave Appliance - Debian

Overview

This articleguide providesexplains stepshow forto extendinguse 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 partition residing in a logical volume created(LV) withto Logicalconsume Volumeavailable Managerspace
  • Grows the root filesystem online (LVM)supports inext4, aext3, virtualext2, machineand runningXFS)
    • on
  • Repairs Debian.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-stepStep guideInstructions

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 Debianreal:

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 commandsscript supports several command-line options:

Verbose Mode

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

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 Debianlive systems).

Solution: These warnings are asnormal follows.and Performsafe to ignore. The script continues and typically succeeds anyway.

Common Scenarios

Scenario 1: Expand 50GB Appliance to 100GB

  1. At hypervisor level: Resize the commandsvirtual asdisk rootfrom 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 useLV. sudoPlan beforeaccordingly.

each

Support

command and know that these are meant for the FileWave Appliance images.

If you useencounter yourissues ownor Debianhave installquestions:

you
    can still expand your partitions but
  1. Review the namessupport 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 disks and partitions will differ so you'll need to adjust the commands used. 

      # Make sure the tools are present
sudo apt update
sudo apt install -y cloud-guest-utils

# Extend the partitions
sudo growpart /dev/sda 2 || true

# Older Appliances will use the next 2 lines
# If you get an error for them then you should
# try the next 2 lines.
sudo growpart /dev/sda 5 || true
sudo pvresize /dev/sda5

# Newer Appliances will use the next 2 lines
# Do these if the prior 2 lines showed an error
# There is no harm in running the prior lines and these
sudo growpart /dev/sda 3 || true
sudo pvresize /dev/sda3

# Next lines are for all appliances
sudo lvextend -l +100%FREE /dev/mapper/Debian--12--vg-root
sudo resize2fs /dev/mapper/Debian--12--vg-root
sudo reboot

      Troubleshooting

        issue
      • IfOutput youfrom are receiving an error referencing that Debian--12--vg-root does not exist, try running "df -h" and pay careful attention to what comes afterh /dev/mapper/, inlvs, thevgs, results. You will need to run "sudo lvextend -l +100%FREE /dev/mapper/Debian--12--vg-root" and "sudo resize2fs /dev/mapper/Debian--12--vg-root" instead with the actual lv name you have configured.
      • If you get an error that sudo: 'Account or password is expired, reset your password and try again' or 'sudo: unable to change expired password: Authentication token manipulation error' - then you are likely already logged in as root. Just omit using sudo at the beginning of the above commands and you should be able to expand the disk.
        pvs

      Related Content

 

Back to top