FreeBSD SCSI Tape Operations: Position, Stream, Verify, and Retire Media

Sequential-access tape behaves differently from a disk. It has a current position, filemarks, records, drive state, and device nodes whose close behavior can rewind or leave the tape positioned. A command that reads successfully from a file is not a valid tape acceptance test, and a backup command that exits zero does not prove that the media can be restored.

FreeBSD’s sa(4) driver exposes SCSI sequential-access devices, while mt(1) controls positioning and status. The exact drive capabilities, compression, block behavior, and device nodes depend on hardware and driver configuration. Inventory the drive and use its vendor documentation for media compatibility rather than assuming every cartridge or tape generation is interchangeable.

Identify the device and node semantics

Start with the SCSI/CAM view and kernel messages:

camcontrol devlist -v
dmesg | grep -iE 'tape|sa[0-9]|sequential'
ls -l /dev/sa* /dev/nsa* 2>/dev/null

The sa manual describes minor-number submodes that affect what happens at close. Rewind-on-close and no-rewind-on-close nodes have materially different behavior. The exact names shown by the host may depend on the configured device, but commonly include sa for rewind and nsa for no-rewind. Check the target system’s mt(1) and sa(4) manuals before scripting.

Do not assume /dev/nsa0 is always the right unit. Correlate the device node with the drive’s SCSI address, serial number, library slot, and operating-system inventory. On a system with a tape library, distinguish the drive from the media changer; moving a cartridge and moving tape position are different operations.

Check state before positioning

Use a status command before any operation that can change tape position:

mt -f /dev/nsa0 status
mt -f /dev/nsa0 rewind
mt -f /dev/nsa0 status

Replace the device node with the verified target. Rewind is a physical media operation and may take substantial time. Do not interrupt a drive during an erase, rewind, or other long-running hardware command simply because the terminal appears quiet.

Tape uses filemarks to separate data sets. Commands such as fsf and bsf move across filemarks; fsr and bsr move across records. They are not interchangeable. The mt manual’s exact command list varies by device and release, so use installed documentation and a test cartridge before writing a runbook that depends on a particular operation.

Use no-rewind nodes only when the workflow deliberately maintains position across close/reopen operations. A process that closes a rewind node can return the medium to beginning-of-tape, making a later append or restore read the wrong region. Conversely, a no-rewind workflow that loses track of position can append at an unintended location. Record current position and expected next filemark in the job log.

Treat a drive’s mount session as stateful. The sa(4) manual describes parameters that remain in effect during a session and documents close behavior for submodes. A close can write a filemark after output and either rewind or leave the tape mounted depending on the device node. This is why a wrapper script should name its exact device path and never rely on an inherited TAPE environment variable from an interactive login.

If a job is composed of multiple data sets, write and record a catalog entry after each completed data set. Include the expected file number and filemark boundary, and verify the next operation’s starting position before appending. Do not assume a process exit leaves the drive at the beginning of the next file; the tape driver’s close mode and application buffering both matter. A second process should not take over the same unit until the first process has closed it and the operator has checked drive status.

Write a backup stream only to approved media

Backup commands overwrite or append to tape. Confirm the cartridge identity, retention policy, expiration date, pool, and drive before starting. The following command is an example of writing a UFS dump to a tape device; it is destructive to the selected tape and should be used only on approved media:

dump -0u -f /dev/nsa0 /home

The exact dump options and filesystem arguments must be checked against the installed dump(8) manual and site policy. The -u option updates dumpdates; do not enable it if the backup schedule does not use that file as its authoritative record. A live filesystem backup may need an FFS snapshot or application coordination, depending on consistency requirements.

Capture the command start and end time, host, filesystem, dump level, tape barcode, drive serial, operator, and exit status. Preserve dump output and kernel messages. If the dump reports media, read, or write errors, mark the cartridge suspect and do not continue a retention rotation that could overwrite the last known-good recovery copy.

Tape drives can buffer data and report completion at different points in the write path. A successful close or filemark operation does not prove the entire data set is readable. Read-back verification is a separate step and can require rewinding or a separate drive pass.

Read and verify without restoring over live data

A table-of-contents operation can validate that a dump header and directory structure are readable, but it is not a full restore drill:

mt -f /dev/nsa0 rewind
restore -t -f /dev/nsa0

The sample reads media from the beginning and may alter tape position. Run it against the correct cartridge and drive. A full restore test should target a disposable filesystem or a separate recovery environment, never an active production path.

For meaningful verification, periodically restore representative directories, preserve ownership and file metadata as required, and compare checksums or application-level invariants. Test the complete chain, including tape mount, drive selection, filemark positioning, dump selection, restore destination, and service validation. A catalog entry saying “verified” is useful only if it records the date, media identifier, method, and result.

Design retention and recovery operations

Use a media rotation policy that records which cartridges are onsite, offsite, expired, encrypted if applicable, and eligible for reuse. Tape labels and barcode inventory must match the backup catalog. Keep at least one tested copy outside the source host and storage failure domain. A tape stored beside the server does not protect against site loss.

A restore procedure should avoid writing into the original filesystem until the alternate restore has been verified. Mount restored data read-only first when practical. Compare filesystem path, dump level, timestamp, file ownership, and required application state. For incremental dumps, retain every required lower-level dump and document the restore order. Missing one predecessor can make a later incremental unusable.

Do not let automation infer that a tape is reusable from a successful rewind. Rewind is not erase, inventory, or retention approval. Likewise, a filesystem device name does not prove which cartridge is loaded. Combine drive status with library inventory and a human- or system-controlled barcode record.

Diagnose common failures

If the device node is missing, inspect CAM discovery, controller configuration, cabling, drive power, and kernel logs. If status fails, check whether another process has the exclusive device open. The sa driver documents tape devices as exclusive-open for ordinary data access, so a backup daemon and a manual mt command may conflict. Stop or coordinate the owning service before taking manual control.

If a positioning operation appears stuck, allow the drive’s documented completion time and inspect status and kernel logs. Do not issue repeated commands blindly; some drives queue or reject operations while media is loading. If a write fails, preserve the cartridge and log for incident analysis before retrying with a known-good scratch medium.

If the backup command succeeded but verification fails, distinguish media read errors from an incorrect filemark position, wrong dump level, wrong device node, or wrong cartridge. Start by recording drive status, tape identity, and the exact sequence of commands. Do not overwrite the only copy while diagnosing.

Maintain separate runbooks for the tape drive and the library changer. The changer moves cartridges into drive slots; mt controls the tape position once media is loaded. A barcode reported by a library is not proof that a particular filesystem dump is present at a given filemark. Confirm that the media label, backup catalog, and restore test all refer to the same cartridge and backup generation.

Environmental conditions and handling matter for long-term media reliability. Follow the media vendor’s storage and cleaning instructions, label cartridges using the approved scheme, and retain cleaning cartridges separately from data inventory. Do not use an arbitrary cleaning cycle as a response to every read error; capture drive logs and isolate whether failures follow a particular cartridge, drive, or batch. A consistent pattern across several tapes can indicate a drive or transport problem rather than bad media.

Acceptance criteria

A tape workflow is production-ready when hardware and node selection are unambiguous, the position model is documented, media is identified by barcode and retention state, one full write/read/restore cycle has succeeded, and failures leave the prior recovery copy untouched. Run restore drills on a schedule and retain evidence with each media set.

Tape is a sequential medium with its own state machine. Treat positioning, record boundaries, filemarks, close behavior, and recovery testing as first-class operational concerns rather than assuming disk-like semantics.

Related:

Sources: