.\" generated with Ronn-NG/v0.9.1
.\" http://github.com/apjanke/ronn-ng/tree/0.9.1
.TH "DWARFS" "1" "April 2024" ""
.SH "NAME"
\fBdwarfs\fR \- mount highly compressed read\-only file system
.SH "SYNOPSIS"
\fBdwarfs\fR \fIimage\fR \fImountpoint\fR [\fIoptions\fR\|\.\|\.\|\.]
.SH "DESCRIPTION"
\fBdwarfs\fR is the FUSE driver for DwarFS, a highly compressed, read\-only file system\. As such, it's similar to file systems like SquashFS, cramfs or CromFS, but it has some distinct features\.
.P
Other than that, it's pretty straightforward to use\. Once you've created a file system image using mkdwarfs(1), you can mount it with:
.P
\fBdwarfs image\.dwarfs /path/to/mountpoint\fR
.SH "OPTIONS"
In addition to the regular FUSE options, \fBdwarfs\fR supports the following options:
.TP
\fB\-o cachesize=\fR\fIvalue\fR
Size of the block cache, in bytes\. You can append suffixes (\fBk\fR, \fBm\fR, \fBg\fR) to specify the size in KiB, MiB and GiB, respectively\. Note that this is not the upper memory limit of the process, as there may be blocks in flight that are not stored in the cache\. Also, each block that hasn't been fully decompressed yet will carry decompressor state along with it, which can use a significant amount of additional memory\. For more details, see mkdwarfs(1)\.
.TP
\fB\-o blocksize=\fR\fIvalue\fR
Size reported for files in \fBst_blksize\fR\. You can use this to optimize throughput in certain situations\.
.TP
\fB\-o readahead=\fR\fIvalue\fR
How much data to read ahead when receiving a read request\. This is experimental and disabled by default\. If you perform a lot of large, sequential reads, throughput may benefit from enabling readahead\.
.TP
\fB\-o workers=\fR\fIvalue\fR
Number of worker threads to use for decompressing blocks\. If you have a lot of CPUs, increasing this number can help speed up access to files in the filesystem\.
.TP
\fB\-o decratio=\fR\fIvalue\fR
The ratio over which a block is fully decompressed\. Blocks are only decompressed partially, so each block has to carry the decompressor state with it until it is fully decompressed\. However, if a certain fraction of the block has already been decompressed, it may be beneficial to just decompress the rest and free the decompressor state\. This value determines the ratio at which we fully decompress the block rather than keeping a partially decompressed block\. A value of 0\.8 means that as long as we've decompressed less than 80% of the block, we keep the partially decompressed block, but if we've decompressed more then 80%, we'll fully decompress it\.
.TP
\fB\-o offset=\fR\fIvalue\fR|\fBauto\fR
Specify the byte offset at which the filesystem is located in the image, or use \fBauto\fR to detect the offset automatically\. This is only useful for images that have some header located before the actual filesystem data\.
.TP
\fB\-o mlock=none\fR|\fBtry\fR|\fBmust\fR
Set this to \fBtry\fR or \fBmust\fR instead of the default \fBnone\fR to try or require \fBmlock()\fRing of the file system metadata into memory\.
.TP
\fB\-o enable_nlink\fR
Set this option if you want correct hardlink counts for regular files\. If this is not specified, the hardlink count will be 1\. Enabling this will slow down the initialization of the fuse driver as the hardlink counts will be determined by a full file system scan (it only takes about a millisecond to scan through 100,000 files, so this isn't dramatic)\. The fuse driver will also consume more memory to hold the hardlink count table\. This will be 4 bytes for every regular file inode\.
.TP
\fB\-o readonly\fR
Show all file system entries as read\-only\. By default, DwarFS will preserve the original writability, which is obviously a lie as it's a read\-only file system\. However, this is needed for overlays to work correctly, as otherwise directories are seen as read\-only by the overlay and it'll be impossible to create new files even in a writeable overlay\. If you don't use overlays and want the file system to reflect its read\-only state, you can set this option\.
.TP
\fB\-o (no_)cache_image\fR
By default, \fBdwarfs\fR tries to ensure that the compressed file system image will not be cached by the kernel (i\.e\. the default is \fB\-o no_cache_image\fR)\. This will reduce the memory consumption of the FUSE driver to slightly more than the \fBcachesize\fR, plus the size of the metadata block\. This usually isn't a problem, especially when the image is stored on an SSD, but if you want to maximize performance it can be beneficial to use \fB\-o cache_image\fR to keep the compressed image data in the kernel cache\.
.TP
\fB\-o (no_)cache_files\fR
By default, files in the mounted file system will be cached by the kernel (i\.e\. the default is \fB\-o cache_files\fR)\. This will significantly improve performance when accessing the same files over and over again, especially if the data from these files has been (partially) evicted from the block cache\. By setting the \fB\-o no_cache_files\fR option, you can force the fuse driver to not use the kernel cache for file data\. If you're short on memory and only infrequently accessing files, this can be worth trying, even though it's likely that the kernel will already do the right thing even when the cache is enabled\.
.TP
\fB\-o debuglevel=\fR\fIname\fR
Use this for different levels of verbosity along with either the \fB\-f\fR or \fB\-d\fR FUSE options\. This can give you some insight over what the file system driver is doing internally, but it's mainly meant for debugging and the \fBdebug\fR and \fBtrace\fR levels in particular will slow down the driver\. This defaults to \fBinfo\fR in foreground mode (\fB\-f\fR, \fB\-d\fR) and to \fBwarn\fR in background mode\.
.TP
\fB\-o tidy_strategy=\fR\fIname\fR
Use one of the following strategies to tidy the block cache:
.TP
\fB\-o tidy_interval=\fR\fItime\fR
Used only if \fBtidy_strategy\fR is not \fBnone\fR\. This is the interval at which the cache tidying thread wakes up to look for blocks that can be removed from the cache\. This must be an integer value\. Suffixes \fBms\fR, \fBs\fR, \fBm\fR, \fBh\fR are supported\. If no suffix is given, the value will be assumed to be in seconds\.
.TP
\fB\-o tidy_max_age=\fR\fItime\fR
Used only if \fBtidy_strategy\fR is \fBtime\fR\. A block will be removed from the cache if it hasn't been used for this time span\. This must be an integer value\. Suffixes \fBms\fR, \fBs\fR, \fBm\fR, \fBh\fR are supported\. If no suffix is given, the value will be assumed to be in seconds\.
.TP
\fB\-o perfmon=\fR\fIname\fR
Enable performance monitoring for the list of comma\-separated components\. This option is only available if the project was built with performance monitoring enabled\. Available components include \fBfuse\fR, \fBfilesystem_v2\fR and \fBinode_reader_v2\fR\.
.TP
\fB\-\-man\fR
If the project was built with support for built\-in manual pages, this option will show the manual page\. If supported by the terminal and a suitable pager (e\.g\. \fBless\fR) is found, the manual page is displayed in the pager\.
.P
There's two particular FUSE options that you'll likely need at some point, e\.g\. when trying to set up an \fBoverlayfs\fR mount on top of a DwarFS image:
.TP
\fB\-o allow_root\fR and \fB\-o allow_other\fR
These will ensure that the mounted file system can be read by either \fBroot\fR or any other user in addition to the user that started the fuse driver\. So if you're running \fBdwarfs\fR as a non\-privileged user, you want to \fB\-o allow_root\fR in case \fBroot\fR needs access, for example when you're trying to use \fBoverlayfs\fR along with \fBdwarfs\fR\. If you're running \fBdwarfs\fR as \fBroot\fR, you need \fBallow_other\fR\.
.SH "TIPS & TRICKS"
.SS "Adding a DwarFS image to /etc/fstab"
This should be relatively straightforward if you're already familiar with adding other FUSE file systems to \fB/etc/fstab\fR\. An entry looks like this:
.P
\fBdwarfs#/path/to/image\.dwarfs /mnt/mountpoint fuse noauto,defaults,user,cachesize=1g 0 0\fR
.P
The first bit before the \fB#\fR tells \fBmount\fR to look for \fBmount\.dwarfs\fR, which is installed as a symbolic link to the DwarFS FUSE driver\. The part after the \fB#\fR looks pretty much like any other \fBfstab\fR entry\. It starts with the path of the file system image to mount, followed by the mount point, followed by the file system type (\fBfuse\fR), and finally followed by a set of options\.
.P
If you want to automatically mount a DwarFS file system, you'll also need the \fBallow_other\fR option to make sure non\-privileged users will be able to access the data\. If you want to work with overlays, you'll need either \fBallow_other\fR or \fBallow_root\fR\. For any of these options to work, you will have to set \fBuser_allow_other\fR in \fB/etc/fuse\.conf\fR\.
.SS "Setting up a writable file system on top of a DwarFS image"
This will show you how to set up a read/write layer on top of a read\-only DwarFS image, which can be incredibly handy if you want to be able to partially and/or temporarily modify/amend the contents of your read\-only image\.
.P
My primary use case for this feature is keeping over 1000 Perl versions in the DwarFS image and then setting up a read/write layer to be able to install additional modules for each of these versions\. When I didn't need the modules anymore, I could just completely wipe the read/write layer and get my pristine original set of Perl versions back\.
.P
Here's what you need to do:
.IP "\[ci]" 4
Create a set of directories\. In my case, these are all located in \fB/tmp/perl\fR as this was the original install location\.
.IP
\fBcd /tmp/perl mkdir install\-ro mkdir install\-rw mkdir install\-work mkdir install\fR
.IP "\[ci]" 4
Mount the DwarFS image\. \fB\-o allow_root\fR is needed to make sure \fBoverlayfs\fR has access to the mounted file system\. In order to use \fB\-o allow_root\fR, you may have to uncomment or add \fBuser_allow_other\fR in \fB/etc/fuse\.conf\fR\.
.IP
\fBdwarfs perl\-install\.dwarfs install\-ro \-o allow_root\fR
.IP "\[ci]" 4
Now set up \fBoverlayfs\fR\.
.IP
\fBsudo mount \-t overlay overlay \-o lowerdir=install\-ro,upperdir=install\-rw,workdir=install\-work install\fR
.IP "\[ci]" 4
That's it\. You should now be able to access a writeable version of your DwarFS image in \fBinstall\fR\.
.IP "" 0
.P
You can go even further than that\. Say you have different sets of modules that you regularly want to layer on top of the base DwarFS image\. In that case, you can simply build a new DwarFS image from the read\-write directory after unmounting the \fBoverlayfs\fR, and selectively add this by passing a colon\-separated list to the \fBlowerdir\fR option when setting up the \fBoverlayfs\fR mount:
.P
\fBsudo mount \-t overlay overlay \-o lowerdir=install\-ro:install\-modules install\fR
.P
If you want \fIthis\fR merged overlay to be writable, just add in the \fBupperdir\fR and \fBworkdir\fR options from before again\.
.SH "AUTHOR"
Written by Marcus Holland\-Moritz\.
.SH "COPYRIGHT"
Copyright (C) Marcus Holland\-Moritz\.
.SH "SEE ALSO"
mkdwarfs(1), dwarfsextract(1), dwarfsck(1), dwarfs\-format(5)