|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Project Overview |
| 6 | + |
| 7 | +This is the reference implementation of the Linear Tape File System (LTFS) format specifications from SNIA, the LTFS format specification 2.5 (https://www.snia.org/sites/default/files/technical-work/ltfs/release/SNIA-LTFS-Format-v2.5-Technical-Position.pdf). |
| 8 | + |
| 9 | +LTFS is a filesystem implementation that allows mounting LTFS-formatted tapes as regular filesystems. LTFS uses Filesystem in Userspace (FUSE) under the foot. |
| 10 | + |
| 11 | +## Build Commands |
| 12 | + |
| 13 | +### Linux Build Configuration |
| 14 | +```bash |
| 15 | +./autogen.sh |
| 16 | +./configure --prefix=</path_to_install> |
| 17 | +``` |
| 18 | + |
| 19 | +### Linux Build |
| 20 | +```bash |
| 21 | +make |
| 22 | +make install |
| 23 | +# May need: sudo ldconfig -v |
| 24 | +``` |
| 25 | + |
| 26 | +### macOS Build Configuration |
| 27 | +```bash |
| 28 | +# Setup environment first: |
| 29 | +export ICU_PATH="/usr/local/opt/icu4c/bin" |
| 30 | +export LIBXML2_PATH="/usr/local/opt/libxml2/bin" |
| 31 | +export PKG_CONFIG_PATH="/usr/local/opt/icu4c/lib/pkgconfig:/usr/local/opt/libxml2/lib/pkgconfig" |
| 32 | +export PATH="$PATH:$ICU_PATH:$LIBXML2_PATH" |
| 33 | + |
| 34 | +./autogen.sh |
| 35 | +LDFLAGS="-framework CoreFoundation -framework IOKit" ./configure --disable-snmp --prefix=</path_to_install> |
| 36 | +``` |
| 37 | + |
| 38 | +### macOS Build |
| 39 | +```bash |
| 40 | +make |
| 41 | +make install |
| 42 | +``` |
| 43 | + |
| 44 | +### Clean Build |
| 45 | +```bash |
| 46 | +make clean |
| 47 | +``` |
| 48 | + |
| 49 | +### Clean up everything |
| 50 | +```bash |
| 51 | +make clean |
| 52 | +make distclean |
| 53 | +``` |
| 54 | + |
| 55 | +## Core Architecture |
| 56 | + |
| 57 | +### Main Components |
| 58 | + |
| 59 | +1. **libltfs** (`src/libltfs/`) - Core LTFS library |
| 60 | + - `ltfs.c/h` - Main LTFS data structures and operations |
| 61 | + - `ltfs_fsops.c` - Filesystem operations implementation |
| 62 | + - `tape.c/h` - Tape drive abstraction layer |
| 63 | + - `index_criteria.c` - Index management logic |
| 64 | + - `xml_reader.c/xml_writer.c` - XML index parsing/generation |
| 65 | + |
| 66 | +2. **Tape Drivers** (`src/tape_drivers/`) |
| 67 | + - Platform-specific tape drive implementations |
| 68 | + - `linux/sg/` - Linux SCSI generic driver |
| 69 | + - `linux/lin_tape/` - IBM lin_tape driver |
| 70 | + - `osx/iokit/` - macOS IOKit driver |
| 71 | + - `freebsd/cam/` - FreeBSD CAM driver |
| 72 | + - `generic/file/` - Debug purpose tape emulation on a directory (for creating situations hard to recreate) |
| 73 | + |
| 74 | +3. **I/O Schedulers** (`src/iosched/`) |
| 75 | + - `fcfs.c` - First-come-first-served scheduler (This is sample of I/O scheduler. Not used at all.) |
| 76 | + - `unified.c` - Unified I/O scheduler with optimization (This I/O scheduler can create 512KB block from chunked requests from FUSE layer) |
| 77 | + |
| 78 | +4. **Key Management** (`src/kmi/`) |
| 79 | + - `simple.c` - Simple key management interface, receive keys from options |
| 80 | + - `flatfile.c` - Flat file-based key storage, receive keys specified unencrypted file |
| 81 | + |
| 82 | +5. **Utilities** (`src/utils/`) |
| 83 | + - `mkltfs.c` - Format tapes for LTFS like `mkfs` |
| 84 | + - `ltfsck.c` - Check and repair LTFS volumes like `fsck` |
| 85 | + - `ltfsindextool.c` - Manipulate LTFS indexes outside of LTFS filesystem implementation |
| 86 | + - `ltfs_ordered_copy` - Python script for optimized file copying |
| 87 | + |
| 88 | +6. **Entry point of `ltfs` process** (`src/main.c`) |
| 89 | + - This is the start point of LTFS filesystem process |
| 90 | + |
| 91 | +7. **ltfs internal filesystem operations** (`src/libltfs/ltfs_fsops.c/h`) |
| 92 | + - This is the ltfs own filesystem operations implementation |
| 93 | + |
| 94 | +8. **FUSE-LTFS bridge** (`ltfs_fuse.c`) |
| 95 | + - This layer converts request from FUSE to the ltfs own filesystem operations |
| 96 | + |
| 97 | +### Key Design Patterns |
| 98 | + |
| 99 | +- **Plugin Architecture**: Tape drivers, I/O schedulers, and key management are implemented as plugins loaded at runtime and called indirectly by pointer |
| 100 | +- **FUSE Integration**: Uses FUSE (Filesystem in Userspace) for filesystem operations |
| 101 | +- **XML Indexes**: Filesystem metadata stored as XML on tape (following LTFS format spec) |
| 102 | +- **Dual Partition**: Uses tape partition feature - index on Index Partition, data on Data Partition |
| 103 | + |
| 104 | +### Important Files to Understand |
| 105 | + |
| 106 | +- `src/libltfs/ltfs_internal.c` - This is low level function called from ltfs.c |
| 107 | +- `src/libltfs/ltfs_fsops_raw.c` - This is low level function to handle LTFS format called sequence is FUSE->FUSE-LTFS bridge->ltfs internal filesystem operations->I/O scheduler->low level function to handle LTFS format |
| 108 | + |
| 109 | +# Tech Stack |
| 110 | +- Language: C99 with gcc |
| 111 | + |
| 112 | +# Project Structure |
| 113 | +- `contrib`: Contribution code that is not a part of the project but is variable for this project |
| 114 | +- `docs`: Documents and configuration files for system. See also docs/README.md |
| 115 | +- `init.d`: Service script for init |
| 116 | +- `man`: man pages for the commands provided by the project |
| 117 | +- `man/sgml`: Original documents for man pages written by docbook 4.1 format |
| 118 | +- `messages`: Message files used in the code tree |
| 119 | +- `src/libltfs`: Source files for libltfs, the library that handles logical layer of the LTFS format |
| 120 | +- `src/iosched`: I/O scheduler plugins for libltfs. The libltfs makes indirect calls to an ioschead plugin loaded when a command is launched for creating 512KB block for tape R/W |
| 121 | +- `src/tape_drivers`: Tape drive handling plugins for libltfs. The libltfs makes indirect calls to an tape drive plugin loaded when a command is launched for issuing SCSI commands to different type of tape drives |
| 122 | +- `src/kmi`: Encryption key management plugins for libltfs |
| 123 | +- `utils/mkltfs.c`: Formatting tool for the LTFS like `mkfs` |
| 124 | +- `utils/ltfsck.c`: Recovery tool for the LTFS like `fsck` |
| 125 | +- `utils/ltfsindextool.c`: Tools for capturing indexes on the tape |
| 126 | +- `./main.c`: Main function for `ltfs` command, it is the file system command for FUSE |
| 127 | +- `./ltfs_fuse.*`: FUSE - LTFS file operation glue layer |
| 128 | +- `./ltfs_copyright.h`: Copyright definition for injecting to compiled binaries |
| 129 | + |
| 130 | +## Common Development Tasks |
| 131 | + |
| 132 | +### Running LTFS Commands |
| 133 | + |
| 134 | +```bash |
| 135 | +# List available tape drives |
| 136 | +ltfs -o device_list |
| 137 | + |
| 138 | +# Format a tape |
| 139 | +mkltfs -d <device_name> |
| 140 | + |
| 141 | +# Mount a tape |
| 142 | +ltfs -o devname=<device_name> <mount_point> |
| 143 | + |
| 144 | +# Unmount |
| 145 | +umount <mount_point> |
| 146 | + |
| 147 | +# Check/repair LTFS volume |
| 148 | +ltfsck -d <device_name> |
| 149 | +``` |
| 150 | + |
| 151 | +### Debugging |
| 152 | + |
| 153 | +- Use `--enable-debug` configure option for debug builds |
| 154 | +- Set log level with `-o loglevel=<level>` (0-4) |
| 155 | +- Check syslog for LTFS messages |
| 156 | + |
| 157 | +## Platform-Specific Notes |
| 158 | + |
| 159 | +- **Linux**: Supports both sg (SCSI generic) and lin_tape drivers |
| 160 | +- **macOS**: Requires disabling SNMP support (`--disable-snmp`) |
| 161 | +- **FreeBSD/NetBSD**: Uses platform-specific SCSI interfaces |
| 162 | + |
| 163 | +## Message System |
| 164 | + |
| 165 | +- Messages defined in `messages/` directory |
| 166 | +- Message is constructed a number and sevirity (Error, Warning, Info, Debug) |
| 167 | +- Number part of message must be unique |
| 168 | + - It means 11111W must not be used if 11111I is used |
| 169 | +- Number part of message must not be reused once used |
| 170 | + - It means 11111[EWID] must not be used if 11111[EWID] is already commented out |
| 171 | +- Message ID must be commented out when it is not required anymore |
| 172 | +- Each component has its own message file |
| 173 | +- Run `make_message_src.sh` to regenerate message headers |
| 174 | + |
| 175 | +# Do Not Section |
| 176 | +- Do not commit directly to the any branches |
| 177 | +- Do not provide any changes which cannot be compiled |
| 178 | +- Do not use duplicated messege number under the `messages` directory |
| 179 | +- Do not reuse any message number which is commented out inder the `messages` directory |
0 commit comments