summaryrefslogtreecommitdiff
path: root/README
blob: b92502d727f108e16b7926f59b26052ab9257872 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110

 About
 *****

SquashFS is a highly compressed, read only file system often used as a root fs
on embedded devices, live systems or simply as a compressed archive format.

Think of it as a .tar.gz that you can mount (or XZ, LZO, LZ4, ZSTD).

The file system itself and the user space tooling were originally developed by
Phillip Lougher with third party contributions that have accumulated over time.

Unfortunately, the original user space tooling does not support a lot of
standard use cases, the source code of the tools is in a pretty deteriorated
state and apparently no longer maintained.

This package contains the source code of a complete rewrite of the user space
tools that attempt to address many of the problems of the old tools:

 - Reproducible SquashFS images, i.e. deterministic packing without
   any local time stamps.
 - Linux `gen_init_cpio` like file listing for micro managing the
   file system contents, permissions, and ownership without having to replicate
   the file system (and especially permissions) locally.
 - Support for SELinux contexts file (see selabel_file(5)) to generate
   SELinux labels.
 - Structured and (hopefully) more readable source code that should be better
   maintainable in the long run.


In addition to that, tools have been added to directly convert a tar archive
into a SquashFS file system image and back. Although the scope of those tools
is limited, and it is suggested to only use those for quick testing, this
allows for using existing tools can work on tar archives to on SquashFS
images.


The tools in this package have different names, so they can be installed in
together with the existing tools:

 - `gensquashfs` can be used to produce SquashFS images from `gen_init_cpio`
   like file listings or simply pack an input directory.
 - `rdsquashfs` can be used to inspect and unpack SquashFS images.
 - `sqfs2tar` can turn a SquashFS image into a tar ball, written to stdout.
 - `tar2sqfs` can turn a tar ball (read from stdin) into a SquashFS image.


 Limitations
 ***********

At the moment, the following things still require some work:

 - more testing
 - extended attributes
    - currently limited to SELinux labeling only
    - rdsquashfs ignores them entirely
    - SquashFS supports deduplicating values through "out of line"
      storage but this is currently not used yet.
 - sparse files (not implemented yet; lots of zeros compress good anyway :P)
 - hard links (not implemented yet; do we even want this?)
 - File deduplication (not implemented; do we even need this?)
 - NFS export tables (not implemented yet)


At the moment, tar2sqfs also has some limitations on what it can process:
 - only POSIX tar archives with pax extensions (use --posix for GNU tar)
 - no sparse files or hard links (converted to symlink)
 - way fewer tuning options than gensquashfs


 Future plans
 ************

In addition to the above, the following things would be really nice to
have eventually:

 - A tool for merging multiple images into one
 - A tool for splitting an image
 - A diff tool
    - Diff of the directory tree of two images
    - Diff of the file meta data in two images
    - File level diffs
    - Combinations of the above in a still human readable form
 - [IN PROGRESS] A *complete* specification of the on-disk format and all the
   arbitrary checks enforced by the kernel.
 - Patching kernel and user space to support SquashFS on top of UBI
 - Patching kernel and user space to support ACLs


 Copyright & License
 *******************

The source code in this package has been written by me, David Oberhollenzer,
in 2019 and is released under the terms and conditions of the GNU General
Public License version 3 or later.

To the best of my knowledge, no code has been copied over from the original
SquashFS tools. The kernel documentation, the kernel headers and this web site
have been used as main sources for understanding SquashFS:

  https://dr-emann.github.io/squashfs/

Some additional information (such as xattr implementation) has been gathered
from various mailing lists and other web sources.

Compressor implementations are primarily based on the documentation of the
compression libraries.

The existing unsquashfs tool and kernel implementation were used for trial and
error testing during development.