use std::io::{Read, Seek, SeekFrom, Write};
use crate::bytes::{get_u16, get_u32, get_u32_be, put_arr, put_u32, put_u32_be};
use crate::crc32c::crc32c;
use crate::feature::Incompat;
use crate::geometry::carries_superblock;
use crate::io::{Bounded, offset_of, read_exact_at};
use crate::journal;
use crate::ondisk::{SuperBlock, superblock_checksum};
use crate::read::{INCOMPAT_RECOVER, OpenOptions, ReadError, Reader};
#[derive(Clone, Copy, Default, PartialEq, Eq, Debug)]
#[non_exhaustive]
pub struct IdentityChange {
pub uuid: Option<[u8; 16]>,
pub volume_name: Option<[u8; 16]>,
pub set_checksum_seed: bool,
}
impl IdentityChange {
#[must_use]
pub fn new() -> Self {
Self::default()
}
#[must_use]
pub fn is_empty(&self) -> bool {
self.uuid.is_none() && self.volume_name.is_none() && !self.set_checksum_seed
}
}
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
#[non_exhaustive]
pub struct IdentityReport {
pub superblocks: u32,
pub journal_superblock: bool,
pub checksum_seed_set: bool,
}
#[derive(Debug, thiserror::Error)]
#[non_exhaustive]
pub enum IdentityError {
#[error(transparent)]
Io(#[from] std::io::Error),
#[error(transparent)]
Read(#[from] ReadError),
#[error(
"changing the UUID would invalidate every metadata checksum: this filesystem has \
metadata_csum without metadata_csum_seed, so its checksums are seeded from the \
UUID itself — set the checksum seed to keep them valid"
)]
UuidWouldInvalidateChecksums,
#[error(
"setting the checksum seed needs a filesystem with metadata_csum, and this one has \
none: nothing in it is seeded from the UUID"
)]
ChecksumSeedPointless,
#[error(
"group {group}'s backup superblock lies past the end of a {blocks}-block image: \
the superblock describes a larger filesystem than the image holds"
)]
#[non_exhaustive]
BackupPastEnd {
group: u32,
blocks: u64,
},
#[error(
"group {group} should hold a backup superblock at block {block} and does not: \
re-identifying would leave the copies disagreeing about the filesystem"
)]
#[non_exhaustive]
BackupNotASuperblock {
group: u32,
block: u64,
},
#[error(
"the superblock in group {group} has checksum {found:#010x} but its contents \
compute to {computed:#010x}: the image is damaged, and re-identifying it would \
write a correct checksum over a wrong superblock"
)]
#[non_exhaustive]
SuperblockChecksumMismatch {
group: u32,
found: u32,
computed: u32,
},
#[error(
"the journal superblock's checksum is {found:#010x} but its contents compute to \
{computed:#010x}: the log is damaged, and re-identifying it would write a correct \
checksum over a wrong journal superblock"
)]
#[non_exhaustive]
JournalChecksumMismatch {
found: u32,
computed: u32,
},
#[error(
"the filesystem needs journal recovery, which writes any journaled copy of the \
superblock back over a new identity: recover it first, by mounting it or with e2fsck"
)]
NeedsRecovery,
#[error(
"the journal declares checksums of type {checksum_type} rather than crc32c, so its \
superblock checksum cannot be brought back into agreement with a new UUID"
)]
#[non_exhaustive]
JournalChecksumUnsupported {
checksum_type: u8,
},
}
pub fn rewrite_identity<F: Read + Write + Seek>(
image: &mut F,
change: &IdentityChange,
) -> Result<IdentityReport, IdentityError> {
rewrite_identity_at(image, change, 0, None)
}
pub fn rewrite_identity_at<F: Read + Write + Seek>(
image: &mut F,
change: &IdentityChange,
base: u64,
len: Option<u64>,
) -> Result<IdentityReport, IdentityError> {
let mut image = Bounded::new(image, base, len);
let plan = plan_rewrite(&mut image, change, base)?;
for (offset, bytes) in &plan.writes {
image.seek(SeekFrom::Start(base + *offset))?;
image.write_all(bytes)?;
}
image.flush()?;
Ok(plan.report)
}
struct Rewrite {
writes: Vec<(u64, Vec<u8>)>,
report: IdentityReport,
}
fn plan_rewrite<F: Read + Write + Seek>(
image: &mut F,
change: &IdentityChange,
base: u64,
) -> Result<Rewrite, IdentityError> {
let primary = read_exact_at(image, base.saturating_add(1024), SuperBlock::SIZE)?;
if get_u16(&primary, SuperBlock::MAGIC_OFFSET) == crate::ondisk::SUPERBLOCK_MAGIC
&& get_u32(&primary, SuperBlock::FEATURE_INCOMPAT_OFFSET) & INCOMPAT_RECOVER != 0
{
return Err(IdentityError::NeedsRecovery);
}
let mut reader = Reader::open_with(&mut *image, &OpenOptions::new().base(base))?;
let feature = reader.feature();
let sb = reader.superblock().clone();
let group_count = reader.group_count();
let block_size = u64::from(feature.block_size);
let journal_block = if change.uuid.is_some() {
reader.journal_superblock_block()?
} else {
None
};
drop(reader);
let checksummed = feature.has_metadata_csum();
let seeded = feature.has_csum_seed();
let seed_to_set = decide_checksum_seed(change, &sb, checksummed, seeded)?;
let source_blocks = image.seek(SeekFrom::End(0))?.saturating_sub(base) / block_size;
let mut copies = vec![(0u32, 1024u64)];
for group in 1..group_count {
let block = match offset_of(
u64::from(sb.first_data_block),
u64::from(group),
u64::from(sb.blocks_per_group),
) {
Some(block) if block < source_blocks => block,
_ => {
return Err(IdentityError::BackupPastEnd {
group,
blocks: source_blocks,
});
}
};
if !carries_superblock(group, &sb) {
continue;
}
let offset = offset_of(0, block, block_size).ok_or(IdentityError::BackupPastEnd {
group,
blocks: source_blocks,
})?;
copies.push((group, offset));
}
let superblocks = u32::try_from(copies.len()).unwrap_or(u32::MAX);
let mut writes = Vec::with_capacity(copies.len() + 1);
let mut seed_turned_on = false;
for (group, offset) in copies {
let mut bytes = read_exact_at(image, base + offset, SuperBlock::SIZE)?;
if get_u16(&bytes, SuperBlock::MAGIC_OFFSET) != crate::ondisk::SUPERBLOCK_MAGIC {
return Err(IdentityError::BackupNotASuperblock {
group,
block: offset / block_size,
});
}
if checksummed {
verify_checksum(&bytes, group)?;
}
seed_turned_on |= patch(&mut bytes, change, seed_to_set, checksummed);
writes.push((offset, bytes));
}
let journal_written = match (journal_block, change.uuid) {
(Some(block), Some(uuid)) => {
let offset = offset_of(0, block, block_size).ok_or(IdentityError::BackupPastEnd {
group: 0,
blocks: source_blocks,
})?;
let mut bytes = read_exact_at(image, base + offset, journal::SUPERBLOCK_SIZE)?;
patch_journal(&mut bytes, uuid)?;
writes.push((offset, bytes));
true
}
_ => false,
};
Ok(Rewrite {
writes,
report: IdentityReport {
superblocks,
journal_superblock: journal_written,
checksum_seed_set: seed_turned_on,
},
})
}
fn decide_checksum_seed(
change: &IdentityChange,
sb: &SuperBlock,
checksummed: bool,
seeded: bool,
) -> Result<Option<u32>, IdentityError> {
if !checksummed {
if change.set_checksum_seed {
return Err(IdentityError::ChecksumSeedPointless);
}
return Ok(None);
}
if seeded {
let wanted = change.set_checksum_seed || change.uuid.is_some();
return Ok(wanted.then_some(sb.checksum_seed));
}
if change.set_checksum_seed {
return Ok(Some(crc32c(!0, &sb.uuid)));
}
if change.uuid.is_some() {
return Err(IdentityError::UuidWouldInvalidateChecksums);
}
Ok(None)
}
fn patch(bytes: &mut [u8], change: &IdentityChange, seed: Option<u32>, checksummed: bool) -> bool {
if let Some(uuid) = change.uuid {
put_arr(bytes, SuperBlock::UUID_OFFSET, &uuid);
}
if let Some(label) = change.volume_name {
put_arr(bytes, SuperBlock::VOLUME_NAME_OFFSET, &label);
}
let mut turned_on = false;
if let Some(seed) = seed {
put_u32(bytes, SuperBlock::CHECKSUM_SEED_OFFSET, seed);
let incompat = get_u32(bytes, SuperBlock::FEATURE_INCOMPAT_OFFSET);
turned_on = incompat & Incompat::CSUM_SEED.bits() == 0;
put_u32(
bytes,
SuperBlock::FEATURE_INCOMPAT_OFFSET,
incompat | Incompat::CSUM_SEED.bits(),
);
}
if checksummed {
put_u32(
bytes,
SuperBlock::CHECKSUM_OFFSET,
superblock_checksum(bytes),
);
}
turned_on
}
fn patch_journal(bytes: &mut [u8], uuid: [u8; 16]) -> Result<(), IdentityError> {
let checksummed = journal::superblock_is_checksummed(bytes);
if checksummed {
let kind = bytes[journal::offset::CHECKSUM_TYPE];
if kind != journal::CRC32C_CHKSUM {
return Err(IdentityError::JournalChecksumUnsupported {
checksum_type: kind,
});
}
let found = get_u32_be(bytes, journal::offset::CHECKSUM);
let computed = journal::superblock_checksum(bytes);
if found != computed {
return Err(IdentityError::JournalChecksumMismatch { found, computed });
}
}
put_arr(bytes, journal::offset::UUID, &uuid);
if checksummed {
put_u32_be(
bytes,
journal::offset::CHECKSUM,
journal::superblock_checksum(bytes),
);
}
Ok(())
}
fn verify_checksum(bytes: &[u8], group: u32) -> Result<(), IdentityError> {
let found = get_u32(bytes, SuperBlock::CHECKSUM_OFFSET);
let computed = superblock_checksum(bytes);
if found != computed {
return Err(IdentityError::SuperblockChecksumMismatch {
group,
found,
computed,
});
}
Ok(())
}
#[cfg(test)]
mod tests {
use super::*;
use crate::feature::Profile;
use crate::materialize::{FormatOptions, format};
use crate::source::{Metadata, TreeBuilder};
use crate::time::Timestamp;
use std::io::Cursor;
const MIB: u64 = 1024 * 1024;
fn options(profile: Profile) -> FormatOptions {
FormatOptions::new([0x11; 16], Timestamp::from_secs(1_700_000_000), [0u8; 16])
.profile(profile)
}
fn image(profile: Profile) -> Vec<u8> {
let time = Timestamp::from_secs(1_700_000_000);
let source = TreeBuilder::new().file(
b"/a".to_vec(),
b"contents\n".to_vec(),
Metadata::new(0o644, time),
);
format(source, 8 * MIB, options(profile))
.expect("format")
.into_bytes()
}
fn put_u32(bytes: &mut [u8], field: usize, value: u32) {
bytes[1024 + field..1024 + field + 4].copy_from_slice(&value.to_le_bytes());
}
fn claim_groups(bytes: &mut [u8], blocks_per_group: u32) -> u64 {
let sb = &bytes[1024..2048];
let first_data_block = u32::from_le_bytes(sb[0x14..0x18].try_into().expect("a word"));
let inodes_per_group = u32::from_le_bytes(sb[0x28..0x2c].try_into().expect("a word"));
let groups =
(u32::MAX / inodes_per_group).min((u32::MAX - first_data_block) / blocks_per_group);
put_u32(bytes, 0x20, blocks_per_group);
put_u32(bytes, 0x04, groups * blocks_per_group + first_data_block);
put_u32(bytes, 0x00, groups * inodes_per_group);
u64::from(groups)
}
#[test]
fn a_superblock_claiming_more_groups_than_the_image_holds_is_refused() {
let mut bytes = image(Profile::Ext2);
assert!(claim_groups(&mut bytes, 8) > 1_000_000);
let mut change = IdentityChange::new();
change.uuid = Some([0x5a; 16]);
let err = rewrite_identity(&mut Cursor::new(&mut bytes), &change)
.expect_err("a geometry the file cannot hold is refused");
assert!(
matches!(err, IdentityError::BackupPastEnd { .. }),
"expected BackupPastEnd, got {err:?}"
);
}
#[test]
fn a_group_size_that_puts_the_first_backup_past_the_image_is_refused_at_that_group() {
let mut bytes = image(Profile::Ext2);
let block_size = 1024u32
<< u32::from_le_bytes(bytes[1024 + 0x18..1024 + 0x1c].try_into().expect("a word"));
claim_groups(&mut bytes, 8 * block_size);
let mut change = IdentityChange::new();
change.uuid = Some([0x5a; 16]);
let err = rewrite_identity(&mut Cursor::new(&mut bytes), &change)
.expect_err("an unreachable backup is refused");
assert!(
matches!(err, IdentityError::BackupPastEnd { group: 1, .. }),
"expected BackupPastEnd at group 1, got {err:?}"
);
}
#[test]
fn an_untouched_image_still_rewrites_every_copy() {
let mut bytes = image(Profile::Ext2);
let mut change = IdentityChange::new();
change.uuid = Some([0x5a; 16]);
let report = rewrite_identity(&mut Cursor::new(&mut bytes), &change).expect("rewrite");
assert!(report.superblocks >= 1);
let reader = Reader::open(Cursor::new(bytes.as_slice())).expect("open");
assert_eq!(reader.superblock().uuid, [0x5a; 16]);
}
#[test]
fn a_filesystem_longer_than_its_region_is_refused_and_what_follows_is_untouched() {
const BASE: usize = MIB as usize;
let fs = multi_group_image(options(Profile::Ext2));
let mut disk = vec![0u8; BASE];
disk.extend_from_slice(&fs);
let mut change = IdentityChange::new();
change.uuid = Some([0x5a; 16]);
let before = disk.clone();
let err = rewrite_identity_at(
&mut Cursor::new(&mut disk),
&change,
BASE as u64,
Some(16 * MIB),
)
.expect_err("a group past the region is refused");
assert!(
matches!(
err,
IdentityError::BackupPastEnd {
group: 2,
blocks: 16384,
..
}
),
"expected BackupPastEnd at group 2 of a 16 MiB region, got {err:?}"
);
assert_eq!(disk, before, "a refused rewrite writes nothing");
let report = rewrite_identity_at(&mut Cursor::new(&mut disk), &change, BASE as u64, None)
.expect("rewrite");
assert_eq!(report.superblocks, 3, "groups 0, 1 and 3 carry a copy");
}
struct Recording {
inner: Cursor<Vec<u8>>,
writes: Vec<(usize, Vec<u8>)>,
}
impl Read for Recording {
fn read(&mut self, buf: &mut [u8]) -> std::io::Result<usize> {
self.inner.read(buf)
}
}
impl Seek for Recording {
fn seek(&mut self, pos: SeekFrom) -> std::io::Result<u64> {
self.inner.seek(pos)
}
}
impl Write for Recording {
fn write(&mut self, buf: &[u8]) -> std::io::Result<usize> {
let at = usize::try_from(self.inner.position()).expect("an in-memory offset");
let n = self.inner.write(buf)?;
self.writes.push((at, buf[..n].to_vec()));
Ok(n)
}
fn flush(&mut self) -> std::io::Result<()> {
self.inner.flush()
}
}
fn policies() -> [(&'static str, FormatOptions); 3] {
let plain = options(Profile::Ext2);
let seeded = options(Profile::Ext4);
let mut from_uuid = options(Profile::Ext4);
from_uuid.feature.incompat =
Incompat::from_bits(from_uuid.feature.incompat.bits() & !Incompat::CSUM_SEED.bits());
[
("no metadata_csum", plain),
("metadata_csum_seed", seeded),
("metadata_csum seeded from the UUID", from_uuid),
]
}
fn multi_group_image(mut options: FormatOptions) -> Vec<u8> {
options.feature = options.feature.with_block_size(1024);
let time = Timestamp::from_secs(1_700_000_000);
let source = TreeBuilder::new().file(
b"/a".to_vec(),
b"contents\n".to_vec(),
Metadata::new(0o644, time),
);
format(source, 32 * MIB, options)
.expect("format")
.into_bytes()
}
fn every_change() -> Vec<IdentityChange> {
let mut out = Vec::new();
for uuid in [None, Some([0x5a; 16])] {
for volume_name in [None, Some(*b"relabelled\0\0\0\0\0\0")] {
for set_checksum_seed in [false, true] {
let mut change = IdentityChange::new();
let IdentityChange {
uuid: u,
volume_name: v,
set_checksum_seed: s,
} = &mut change;
*u = uuid;
*v = volume_name;
*s = set_checksum_seed;
out.push(change);
}
}
}
out
}
#[test]
fn whichever_writes_landed_a_second_run_reaches_the_same_bytes() {
let mut swept = 0;
for (policy, options) in policies() {
let checksummed = options.feature.has_metadata_csum();
let seeded = options.feature.has_csum_seed();
let original = multi_group_image(options);
for change in every_change() {
let refused_up_front = (change.set_checksum_seed && !checksummed)
|| (change.uuid.is_some()
&& checksummed
&& !seeded
&& !change.set_checksum_seed);
let mut first = Recording {
inner: Cursor::new(original.clone()),
writes: Vec::new(),
};
let result = rewrite_identity(&mut first, &change);
if refused_up_front {
assert!(result.is_err(), "{policy}, {change:?}: expected a refusal");
assert!(
first.writes.is_empty(),
"{policy}, {change:?}: a refusal wrote"
);
continue;
}
let report =
result.unwrap_or_else(|e| panic!("{policy}, {change:?}: the uncut run: {e}"));
let target = first.inner.into_inner();
let writes = first.writes;
assert_eq!(
writes[0].0, 1024,
"{policy}, {change:?}: the primary goes first"
);
assert_eq!(
writes.len(),
report.superblocks as usize + usize::from(report.journal_superblock),
"{policy}, {change:?}: one write per copy"
);
assert_eq!(
report.superblocks, 3,
"{policy}: copies in groups 0, 1, and 3"
);
for landed in 0u32..1 << writes.len() {
let mut bytes = original.clone();
for (i, (at, data)) in writes.iter().enumerate() {
if landed & (1 << i) != 0 {
bytes[*at..*at + data.len()].copy_from_slice(data);
}
}
rewrite_identity(&mut Cursor::new(&mut bytes), &change).unwrap_or_else(|e| {
panic!(
"{policy}, {change:?}, writes {landed:#b} landed: the second run: {e}"
)
});
assert!(
bytes == target,
"{policy}, {change:?}, writes {landed:#b} landed: the second run did \
not reach the uncut run's bytes"
);
swept += 1;
}
}
}
assert_eq!(swept, 32 + 96 + 64, "the cases the sweep ran");
}
#[test]
fn a_copy_torn_partway_through_its_write_is_refused_as_damaged() {
let original = multi_group_image(options(Profile::Ext4));
let mut change = IdentityChange::new();
change.uuid = Some([0x5a; 16]);
let mut first = Recording {
inner: Cursor::new(original.clone()),
writes: Vec::new(),
};
rewrite_identity(&mut first, &change).expect("the uncut run");
for (copy, (at, data)) in first.writes.iter().take(2).enumerate() {
let mut bytes = original.clone();
bytes[*at..*at + 512].copy_from_slice(&data[..512]);
let err = rewrite_identity(&mut Cursor::new(&mut bytes), &change)
.expect_err("a torn copy is refused");
match copy {
0 => assert!(
matches!(
err,
IdentityError::Read(ReadError::ChecksumMismatch { .. })
| IdentityError::SuperblockChecksumMismatch { group: 0, .. }
),
"a torn primary: {err:?}"
),
_ => assert!(
matches!(
err,
IdentityError::SuperblockChecksumMismatch { group: 1, .. }
),
"a torn backup: {err:?}"
),
}
}
}
#[test]
fn a_filesystem_needing_recovery_is_refused_untouched() {
let mut bytes = image(Profile::Ext4);
let at = 1024 + SuperBlock::FEATURE_INCOMPAT_OFFSET;
let incompat = get_u32(&bytes, at) | INCOMPAT_RECOVER;
bytes[at..at + 4].copy_from_slice(&incompat.to_le_bytes());
let before = bytes.clone();
let mut change = IdentityChange::new();
change.volume_name = Some(*b"relabelled\0\0\0\0\0\0");
let err = rewrite_identity(&mut Cursor::new(&mut bytes), &change)
.expect_err("a filesystem needing recovery is refused");
assert!(matches!(err, IdentityError::NeedsRecovery), "{err:?}");
assert!(bytes == before, "nothing was written");
}
#[test]
fn the_seed_asked_for_again_is_already_recorded() {
let mut bytes = multi_group_image(options(Profile::Ext4));
let mut change = IdentityChange::new();
change.uuid = Some([0x5a; 16]);
change.set_checksum_seed = true;
let report = rewrite_identity(&mut Cursor::new(&mut bytes), &change).expect("rewrite");
assert!(!report.checksum_seed_set, "every copy already carried it");
let mut bytes = multi_group_image(options(Profile::Ext2));
let err = rewrite_identity(&mut Cursor::new(&mut bytes), &change)
.expect_err("no metadata_csum, nothing to seed");
assert!(
matches!(err, IdentityError::ChecksumSeedPointless),
"{err:?}"
);
}
}