How to Expand Linux Filesystem Capacity Online Using LVM

1. Identify the real source of the filesystem

Start from the mount point instead of guessing device names. df shows capacity and usage, findmnt reveals the mount source and filesystem type, and lsblk displays device topology.

#!/usr/bin/env bash
set -euo pipefail

MOUNT_POINT="<mount_point>"

df -hT "<mount_point>"
findmnt -T "<mount_point>" -o TARGET,SOURCE,FSTYPE,OPTIONS
lsblk -o NAME,KNAME,TYPE,SIZE,FSTYPE,MOUNTPOINTS

For example, findmnt may show /dev/mapper/vgdata-lvapp, a UUID, or an encrypted mapping. Subsequent commands must use the confirmed LV or PV; never treat the name shown by df as a raw partition.

Resolve symbolic links and inspect LVM mapping relationships.

MOUNT_POINT="<mount_point>"
SOURCE="$(findmnt -no SOURCE -T "<mount_point>")"

echo "source=$SOURCE"
readlink -f "<source>"
sudo pvs -o pv_name,vg_name,pv_size,pv_free
sudo vgs -o vg_name,vg_size,vg_free,pv_count,lv_count
sudo lvs -a -o vg_name,lv_name,lv_path,lv_size,lv_attr,devices

If the mount source is not an LVM LV (e.g., /dev/sda2, NFS, CephFS, or a container volume), the lvextend workflow does not apply; use the appropriate storage‑type expansion method.

2. Determine filesystem type and online capability

ext4 can be enlarged online with resize2fs; XFS uses xfs_growfs. Their commands and shrink capabilities differ, so never mix them. Verify the version and tools first.

findmnt -T <mount_point> -no SOURCE,FSTYPE,OPTIONS
resize2fs -V 2>&1 || true
xfs_growfs -V 2>&1 || true
lvm version

For ext4, avoid running e2fsck on a mounted read‑write filesystem; a full consistency check requires an offline window. For XFS, xfs_repair is also not an online tool. The key before online expansion is to ensure the device, mount, and space relationships are correct, not to run repair commands on a production mount point.

3. Verify where the extra capacity comes from

If the VG already has free space, compare VG Free with the planned increase, remembering the conversion between G, GiB, and PE units, and keep a safety margin.

sudo vgs <vg_name> -o vg_name,vg_size,vg_free,vg_extent_size,vg_free_count
sudo lvs <vg_name>/<lv_name> -o lv_name,lv_size,lv_path,segtype,devices

If VG free space is insufficient, first determine whether the underlying virtual disk has already been enlarged in the cloud or storage layer, or whether a new PV is needed. Do not run pvresize or pvcreate on the wrong block device.

Record the current block‑device size, partition table, and kernel‑seen capacity.

lsblk -b -o NAME,SIZE,TYPE,FSTYPE,MOUNTPOINTS <pv_device>
sudo parted -s <disk_device> unit GiB print
sudo blockdev --getsize64 <pv_device>

parted print

is read‑only; if the underlying disk size has not changed, no amount of pvresize will magically create free space.

4. Back up LVM metadata before changing anything

LVM stores metadata in /etc/lvm/backup and /etc/lvm/archive, but a production change should still export the specific VG configuration and save the current state. This backup helps recover LVM metadata only; it does not replace business data backups or filesystem snapshots.

#!/usr/bin/env bash
set -euo pipefail

VG_NAME="<vg_name>"
BACKUP_DIR="<backup_dir>/lvm-$(date +%Y%m%d-%H%M%S)"

install -d -m 0700 "<backup_dir>"
sudo vgcfgbackup -f "<backup_dir>/<vg_name>.conf" "<vg_name>"
sudo pvs -a -o+pv_uuid > "<backup_dir>/pvs.txt"
sudo vgs -a -o+vg_uuid > "<backup_dir>/vgs.txt"
sudo lvs -a -o+lv_uuid,devices > "<backup_dir>/lvs.txt"
findmnt -T <mount_point> > "<backup_dir>/findmnt.txt"

Ensure the backup files are readable, the backup directory is not on the storage that will be expanded, and that business data backups already exist.

5. Path 1 – VG already has free space

First perform a dry‑run test with lvextend --test, which calculates metadata without writing it. This checks feasibility but does not simulate filesystem expansion.

sudo lvextend --test -L +50G <vg_name>/<lv_name>
sudo lvs <vg_name>/<lv_name> -o lv_name,lv_size,lv_path

After confirming the test, extend the LV and then the filesystem. Never use lvreduce as a rollback; shrinking a LV can truncate filesystem data.

sudo lvextend -L +50G <vg_name>/<lv_name>
sudo lvs <vg_name>/<lv_name> -o lv_name,lv_size,lv_path,devices

For ext4, run resize2fs on the LV path (e.g., /dev/<vg_name>/<lv_name>); for XFS, run xfs_growfs on the mount point.

sudo resize2fs /dev/<vg_name>/<lv_name>
df -hT <mount_point>

sudo xfs_growfs <mount_point>
df -hT <mount_point>

Validate after each step: if the LV grew but the filesystem size did not, df will not show growth. Preserve command output if a filesystem command fails.

6. Path 2 – Underlying disk or partition has already been enlarged

When a cloud disk, SAN LUN, or virtual machine disk is expanded, the kernel may need to rescan the capacity. The following commands only observe the current block device and kernel logs; they do not modify partitions.

lsblk -b -o NAME,SIZE,TYPE <disk_device>
sudo blockdev --getsize64 <disk_device>
journalctl -k --since '-20 min' --no-pager | grep -Ei 'capacity|rescan|sd |nvme' || true

Some SCSI devices can be rescanned via sysfs; the operation must target the real device and will not automatically adjust partitions, PVs, or filesystems.

echo 1 | sudo tee /sys/class/block/<disk_name>/device/rescan
sudo partprobe <disk_device>
lsblk -b -o NAME,SIZE,TYPE <disk_device>

If the PV resides on a whole disk, after the kernel sees the larger size you can test pvresize before applying it.

sudo pvresize --test <pv_device>
sudo pvresize <pv_device>
sudo pvs <pv_device> -o pv_name,pv_size,pv_free,vg_name

If the PV is on a partition, first enlarge the partition safely: confirm partition number, keep the start sector unchanged, have a disk backup, cloud‑snapshot, and a maintenance window. parted resizepart only changes the partition boundary; it does not automatically run pvresize.

sudo parted <disk_device> print
sudo parted <disk_device> resizepart <partition_number> 100%
sudo partprobe <disk_device>
lsblk -o NAME,SIZE,TYPE <disk_device>

After the partition resize, run pvresize --test then pvresize, verify that VG Free increased, and return to Path 1 to finish the LV and filesystem expansion.

7. Path 3 – Add a new disk to the VG

Adding a new disk overwrites any existing signatures or data on that disk. Before proceeding, confirm the device is truly unused with lsblk, blkid, and wipefs -n. In cloud environments also verify volume ID, serial number, and mount relationships.

sudo lsblk -f <new_disk>
sudo blkid <new_disk> || true
sudo wipefs -n <new_disk>
sudo udevadm info --query=all --name=<new_disk> | grep -E 'ID_SERIAL|ID_WWN|DEVNAME'

Only after confirming the device is empty and approved should you create a PV and extend the VG.

sudo pvcreate <new_disk>
sudo vgextend <vg_name> <new_disk>
sudo pvs -o pv_name,vg_name,pv_size,pv_free
sudo vgs <vg_name> -o vg_name,vg_size,vg_free

pvcreate

and vgextend permanently modify LVM metadata and disk signatures; a second‑person review of the device serial, VG name, and change request is recommended.

After the new PV is part of the VG, follow Path 1 to run lvextend and the appropriate filesystem command.

8. Handle PE, striping, mirroring, and thin pools

LVM allocates space in Physical Extents. Most scenarios simply specify +50G or +100%FREE, but striped volumes, RAID LVs, cache, VDO, thin pools, and snapshot volumes have different availability and risk. First check the segment type and thin‑pool usage.

sudo lvs -a -o lv_name,lv_size,lv_attr,segtype,devices,data_percent,metadata_percent,copy_percent <vg_name>
sudo vgs <vg_name> -o vg_name,vg_free,vg_extent_size,vg_free_count

If a thin pool’s Data% or Meta% is near full, expand the thin pool or follow platform‑recommended space‑governance; merely enlarging a thin LV does not guarantee physical space.

9. Verify – not just df

After expansion, validate three layers: LV device size, filesystem free space, and unchanged mount point. Also check that applications have not logged I/O errors or temporary blocks.

sudo lvs <vg_name>/<lv_name> -o lv_name,lv_size,lv_path,devices
findmnt -T <mount_point> -o TARGET,SOURCE,FSTYPE,OPTIONS
df -hT <mount_point>
sudo dmesg --level=err,warn | tail -n 100

If applications report errors during expansion, prioritize data and business consistency, retain kernel and application logs, and remember that a successful LV resize does not automatically adapt upper‑layer databases, containers, or quota settings.

10. Configure monitoring and thresholds

Expansion is not the end of capacity governance. Monitor filesystem availability, inode usage, VG free space, thin‑pool data/metadata usage, disk errors, and application write failures. Use real Prometheus exporter metrics; do not invent metric names.

#!/usr/bin/env bash
set -euo pipefail

MOUNT_POINT="<mount_point>"
VG_NAME="<vg_name>"
LV_NAME="<lv_name>"

df -hT "<mount_point>"
df -ih "<mount_point>"
sudo vgs "<vg_name>" -o vg_name,vg_size,vg_free
sudo lvs "<vg_name>/<lv_name>" -o lv_name,lv_size,lv_attr,segtype,devices,data_percent,metadata_percent

Set alert thresholds based on business write peaks, expansion delivery time, and snapshot‑space buffers. Reacting only at 100 % usage can cause logs, databases, and containers to enter unrecoverable failure states.

11. Make the change auditable

A complete change record should include the initial df, findmnt, lsblk, pvs/vgs/lvs outputs; data‑backup or snapshot IDs; the target increment; the chosen path; actual commands with timestamps; executor and reviewer; post‑expansion validation; any kernel I/O errors; and the next capacity‑alert threshold.

Success is not merely a zero‑exit lvextend; it is verified growth of the mount point, unchanged device‑mount relationships, normal application writes, reasonable VG or thin‑pool free space, restored monitoring, and team awareness of the underlying storage source.

12. Common pitfalls that cause incidents

1. Do not confuse the filesystem size shown by df with the underlying disk size. After a cloud‑disk expansion, partitions, PVs, VGs, LVs, and the filesystem each need verification; missing any layer leaves df unchanged.

2. Do not assume a successful lvextend means the business has gained capacity. If the filesystem command was not run, ran on the wrong device, or the mount point is not the expected LV, applications still see the old size.

3. Avoid using lvreduce to free a small amount of space. Shrinking requires first shrinking the filesystem (ext4 only) and then the LV; XFS cannot be shrunk at all. In production, the safer approach is to create a smaller filesystem, migrate data, switch mounts, and keep a rollback window.

4. Do not treat LVM snapshots as permanent backups. Snapshots consume COW space and can fill quickly under write spikes; their expiration does not replace a proper backup strategy.

13. Post‑expansion capacity governance

A successful expansion usually triggers a re‑evaluation of alert thresholds, growth rates, and responsibility boundaries. Business directories, log directories, container images, database tablespaces, model weights, and temporary files may all compete for space on the same mount point; a total‑usage alert cannot pinpoint the culprit. Implement directory‑level capacity observation, log rotation, object‑storage archiving, and application quotas within business‑allowed limits, and incorporate expansion delivery time into alert lead time.

The LVM layer should retain some VG free space, especially for thin pools, snapshots, emergency expansions, and migrations. Allocating all VG space to a single LV may silence the current alarm but leaves the next failure dependent on adding new disks or high‑risk migrations. Capacity planning aims for clear visibility of storage tiers, growth sources, available margins, and rollback boundaries rather than keeping df perpetually near full.