1 squashfuse - Mount SquashFS archives using FUSE
2
3 https://github.com/vasi/squashfuse
4
5Squashfuse lets you mount SquashFS archives in user-space. It supports almost
6all features of the SquashFS format, yet is still fast and memory-efficient. So
7that everyone can use it, squashfuse supports many different operating systems
8and is available under a permissing license.
9
10SquashFS is an efficiently compressed, read-only storage format. Support for it
11has been built into the Linux kernel since 2009. It is very common on Live CDs
12and embedded Linux distributions.
13
14Quick start:
15 $ ./configure && make
16 $ ./squashfuse foo.squashfs mountpoint
17
18
191. Table of contents
20====================
210. Introduction
221. Table of contents
232. Getting started
24 - System requirements
25 - Getting the source
26 - Building
27 - Usage
283. About squashfuse
29 - Is squashfuse for you?
30 - What's included?
31 - Features
32 - Known bugs
334. References
34 - Licensing
35 - Acknowledgements
36 - Links
37
38
392. Getting started
40==================
41
422a. System requirements
43-----------------------
44To build and use squashfuse, you must be able to use the terminal of your
45operating system.
46
47Runtime requirements:
48 - FUSE 2.5 or later
49 - At least one of the following compression libraries
50 - zlib
51 - lzo2
52 - xz (aka. liblzma)
53 - lz4
54 - (optional) libattr, for better extended attribute support on Linux
55
56Build requirements:
57 - A C compiler
58 - make (any variant)
59 - sed
60 - (optional) pkg-config, for detection of dependencies
61
62To build from the development repository, rather than a tarball, you'll need:
63 - autoconf 2.60 or later
64 - automake 1.11 or later
65 - libtool 2
66
67Known fully-supported platforms:
68 - Linux
69 - Mac OS X
70 - FreeBSD
71 - NetBSD
72 - OpenIndiana
73 - Android
74 - other platforms may work too!
75
76For a precise list of packages you will need on your OS, and other platform
77notes, please see the file `PLATFORMS'.
78
79
802b. Getting the source
81----------------------
82The squashfuse distribution can be downloaded from SourceForge:
83https://sourceforge.net/projects/squashfuse/files/
84
85The development repository uses git, at GitHub:
86http://github.com/vasi/squashfuse
87
88
892c. Installation
90----------------
91Squashfuse is built with the usual `configure && make'. If you need more
92detailed instructions:
93
940. Ensure you're at your terminal, in the directory containing this README.
95
961. (if needed) If the file `configure' is already present, skip this step.
97 Otherwise, run `./autogen.sh' to generate one.
98
992. Run `./configure' to set up the build. You can find useful configuration
100 options in the file `CONFIGURATION', or by running `./configure --help'.
101
102 If configure fails, check that you really have all the requirements
103 installed. You may also want to check the `PLATFORMS' file to see if there
104 are any special notes for your operating system.
105
1063. Run `make' to build `squashfuse'.
107
1084. (optional) If you want to use squashfuse in this directory, that's ok.
109 But if you'd rather install it, run `make install'. If you need root
110 privileges, `sudo make install' may work.
111
112
1132d. Example: Ubuntu
114-------------------
115
116For example on Ubuntu 16.04:
117
118sudo apt-get -y install git autoconf libtool make gcc libtool libfuse-dev liblzma-dev
119libtoolize --force
120aclocal
121autoheader
122automake --force-missing --add-missing
123autoconf
124./configure --with-xz=/usr/lib/
125make
126
127
1282e. Usage
129---------
130You'll need a SquashFS archive to use squashfuse. If you don't already have
131one, you can create one using the `mksquashfs' utility from the squashfs-tools
132project.
133
134To create a SquashFS archive:
135 $ mksquashfs DIRECTORY ARCHIVE
136
137To mount a SquashFS archive with squashfuse:
138 $ squashfuse ARCHIVE MOUNTPOINT
139
140To unmount when you're done:
141 $ umount MOUNTPOINT # On Mac/BSD
142 $ fusermount -u MOUNTPOINT # On Linux
143
144For more options, see the man page squashfuse(1).
145
146
1473. About squashfuse
148===================
149
1503a. Is squashfuse for you?
151--------------------------
152Squashfuse is a great option if you have a SquashFS archive, and:
153 - You're not running Linux, or
154 - You don't have root access, or
155 - You're too concerned about security to use root, or
156 - You find it inconvenient to elevate privileges, or
157 - SquashFS is not built into your kernel, but FUSE is, or
158 - You want to hack on the SquashFS format without risking kernel panics.
159
160Squashfuse is probably not the right tool for the job, if:
161 - You don't have FUSE.
162 More and more systems have FUSE, but some don't. Squashfuse requires it.
163
164 - You have a very old SquashFS archive.
165 Neither squashfuse nor the Linux kernel support SquashFS versions less
166 than 4.0. Use `unsquashfs' from the squashfs-tools project.
167
168 - You want to create or modify a SquashFS archive.
169 Neither squashfuse nor the Linux kernel support write access, use
170 `mksquashfs' from squashfs-tools.
171
172 - You want to extract an entire SquashFS archive.
173 If you don't want to mount anything, it's more efficient and convenient
174 to just use unsquashfs.
175
176 - You want your root filesystem `/' to be SquashFS.
177 This isn't well-tested, though it may be possible.
178
179 - You're highly concerned about bugs.
180 The SquashFS kernel module has seen much more testing than squashfuse.
181
182
183If you don't yet use SquashFS, consider starting, now that squashfuse exists.
184For many uses, the chief drawbacks of SquashFS were requiring Linux and root
185access, but squashfuse has that covered.
186
187 - Use SquashFS for archival and backup, instead of tar.
188 It offers faster creation (multi-core), and browsing without unpacking.
189
190 - Use SquashFS instead of zip.
191 It has better compression, and faster directory lookup.
192
193 - Use SquashFS instead of compressed disk images like DMG, uzip or Partimage.
194 It has better compression and portability.
195
196
1973b. What's included?
198--------------------
199Squashfuse currently comprises three programs:
200
201 * squashfuse Allows you to mount a squashfs filesystem.
202
203 * squashfuse_ll Like `squashfuse', but implemented using the low-level
204 FUSE API. It's a tiny bit faster, but less portable.
205
206 * squashfuse_ls Lists all the files in a squashfs archive. A demonstration
207 of using the squashfuse core in the absence of FUSE.
208
209
2103c. Features
211------------
212Squashfuse supports the following SquashFS features:
213 - zlib, LZO, LZMA2 and LZ4 decompression
214 - Fast, indexed directory lookup
215 - Fast, indexed seeking within files
216 - Caching of decompressed blocks
217 - De-duplicated files
218 - Sparse files
219 - Extended attributes
220 - Files larger than 4GB
221
222Squashfuse is missing the following features:
223 - LZMA1 compression (deprecated)
224 - Support for SquashFS versions less than 4.0
225 - Multi-core decompression
226
227
2283c. Known bugs
229--------------
230- On 32-bit systems with a large inode cache, when mounting a large SquashFS
231 archive created with the "-no-exports" option, squashfuse_ll may use a large
232 amount of memory. This is due to a bug in the FUSE API, where ino_t is shrunk
233 to 32-bits.
234
235
2364. References
237=============
238
2394a. Licensing
240-------------
241Squashfuse is copyright (c) 2012-2014 Dave Vasilevsky <dave@vasilevsky.ca>
242Squashfuse is distributed under the 2-clause BSD license. See the file LICENSE
243for details.
244
245
2464b. Acknowledgements
247--------------------
248Thanks to:
249
250* Phillip Lougher, for designing the SquashFS format, and implementing support
251 in the kernel. Also for providing permission to use and distribute
252 squashfs_fs.h under a BSD-style license.
253
254* Maël Kerbiriou, for implementing LZ4 support.
255
256
2574c. Links
258---------
259* SquashFS
260 - SquashFS home page, includeing squashfs-tools:
261 http://squashfs.sourceforge.net/
262 - squashfs-tools for non-Linux: https://github.com/vasi/squashfs-tools
263
264* FUSE
265 - FUSE home page: http://fuse.sourceforge.net/
266 - OSXFUSE (FUSE for Macs): http://osxfuse.github.io/
267
268* Other implementations of the SquashFS format
269 - Linux kernel: https://github.com/torvalds/linux/tree/master/fs/squashfs
270 - 7-zip / p7zip: http://www.7-zip.org/
271 - GRUB 2 bootloader: http://www.gnu.org/software/grub/
272