This is updated slightly from the last version for a couple of API cleanups and
typos noticed by Tim. Any comments by the end of the week please. Manpages are
attached.
thanks
john
File system image library
1. Summary
This fast-track introduces libfsimage, a simple API for accessing
filesystem images.
Patch release binding is requested.
2. Discussion
The introduction of the Xen hypervisor has created a need to access file
contents residing on an image file or device. Due to the cross-platform nature
of Xen virtualization, and security issues with accessing untrusted
filesystems, accessing the image directly by mounting it via the kernel is
not viable. Instead, a simple user-space library, libfsimage, is provided along
with a number of plugins for popular filesystems. The API is as follows (see
the manpages for full details):
fsi_t *fsi_open_fsimage(const char *path, uint64_t offset);
"Mount" the specified file or device at the given offset. The offset
can be used to get access to a filesystem within a partition or slice.
void fsi_close_fsimage(fsi_t *fsi);
Close a previously opened fsimage.
int fsi_file_exists(fsi_t *fsi, const char *path);
Return 1 if the given path is a regular file on the image.
fsi_file_t *fsi_open_file(fsi_t *fsi, const char *path);
Open the file at the given path.
int fsi_close_file(fsi_file_t *ffi);
Close the given file.
ssize_t fsi_read_file(fsi_file_t *ffi, void *buf, size_t sz);
ssize_t fsi_pread_file(fsi_file_t *ffi, void *buf, size_t sz, uint64_t off);
Read data from the given file.
Due to the implementation of the filesystem plugins and the needs of its
current sole client, no other facilities are provided (such as readdir()).
If such facilities later prove useful, this library can be extended to provide
them.
2.1 Plugins
Plugins are shared libraries located in /usr/lib/fs/<fs>/fsimage.so. The
library attempts to identify the filesystem by loading all plugins located in
the above paths, and running each mount() method until one succeeds. They
provide an entry point :
fsi_plugin_ops_t *fsi_init_plugin(int version, fsi_plugin_t *fp, const char
**name);
where they initialise themselves are return an ops vector as defined in
the attached manpages.
Currently, most of the provided filesystems are based on code from the grub
bootloader. A private fsig_*() API is provided by libfsimage to support this
code.
As of this writing, the supported filesystems are:
Solaris UFS
ext2/3
reiserfs
ZFS support is expected when the ZFS boot project completes.
3. Interface table
The following interfaces are affected by the above.
INTERFACE COMMITMENT LEVEL
fsimage.h
fsi_open_fsimage Committed
fsi_close_fsimage Committed
fsi_file_exists Committed
fsi_open_file Committed
fsi_close_file Committed
fsi_read_file Committed
fsi_pread_file Committed
fsimage_plugin.h
struct fsi_plugin_ops Committed
fsi_init_plugin Committed
fsip_fs_set_data Committed
fsip_file_alloc Committed
fsip_file_free Committed
fsip_fs Committed
fsip_fs_offset Committed
fsip_fs_data Committed
fsip_file_data Committed
fsimage_grub.h
fsig_* XXX Private
4. References
PSARC/2006/260 Solaris on Xen
PSARC/2006/370 ZFS Boot Support
5. Manual pages
See materials.