2004-03-02 14:33:32 +00:00
<?xml version='1.0' encoding='ISO-8859-1'?>
2004-06-07 19:09:22 +00:00
2004-03-02 14:33:32 +00:00
<sect1 id= "mksqoverview" >
2004-06-07 19:09:22 +00:00
2008-03-02 16:06:57 +00:00
<title > The SquashFS tools exposed</title>
2004-03-02 14:33:32 +00:00
<sect2 id= "mksqusing" >
2004-06-07 19:09:22 +00:00
<title > Using mksquashfs</title>
2004-03-02 14:33:32 +00:00
<para >
2004-06-07 19:09:22 +00:00
<command > mksquashfs</command> is the tool for creating new squashed
file systems, and for appending new data to existing squashed file
systems. The general command-line format for <command > mksquashfs</command> is:
2004-03-02 14:33:32 +00:00
</para>
<programlisting >
2004-05-24 20:08:55 +00:00
bash# mksquashfs source1 source2 ... destination [options]
2004-03-02 14:33:32 +00:00
</programlisting>
2004-06-07 19:09:22 +00:00
<itemizedlist >
2008-07-25 16:20:47 +00:00
<listitem > <para > <filename > source1</filename> , <filename > source2</filename> , etc.: files and directories to be
2008-03-02 16:06:57 +00:00
added to the resulting file system, given with relative and/or absolute paths
2008-07-25 16:20:47 +00:00
</para> </listitem>
2004-06-07 19:09:22 +00:00
2008-07-25 16:20:47 +00:00
<listitem > <para > <filename > destination</filename> : a regular file (filesystem
2004-06-07 19:09:22 +00:00
image file), or a block device (such as <filename > /dev/fd0</filename> or <filename > /dev/hda3</filename> )
where you want to have your squashed file system
2008-07-25 16:20:47 +00:00
</para> </listitem>
2004-06-07 19:09:22 +00:00
</itemizedlist>
2004-03-02 14:33:32 +00:00
<para >
2004-06-07 19:09:22 +00:00
Notes for default <command > mksquashfs</command> behavior:
<itemizedlist >
2008-07-25 16:20:47 +00:00
<listitem > <para >
2004-03-02 14:33:32 +00:00
When the new files are added to the new file system or appended to an existing one,
2008-03-02 16:06:57 +00:00
<command > mksquashfs </command> will automatically rename files with duplicate names:
2004-03-02 14:33:32 +00:00
if two or more files named <filename > text</filename> will appear in the same
resulting directory, the second file will be renamed to
<filename > text_1</filename> , third one to <filename > text_2</filename> and so on.
2008-07-25 16:20:47 +00:00
</para> </listitem>
2004-03-02 14:33:32 +00:00
2008-07-25 16:20:47 +00:00
<listitem > <para >
2004-06-07 19:09:22 +00:00
Duplicate files will be removed, so there will be only one physical instance
2008-03-02 16:06:57 +00:00
(By the SquashFS 2.x, you can disable the detection/removal of the duplicates
with the <command > -no-duplicates </command> option).
2008-07-25 16:20:47 +00:00
</para> </listitem>
2004-03-02 14:33:32 +00:00
2008-07-25 16:20:47 +00:00
<listitem > <para >
2008-03-02 16:06:57 +00:00
If <emphasis > destination </emphasis> has a pre-existing SquashFS
2004-06-07 19:09:22 +00:00
file system on it, by default, the new <emphasis > source</emphasis> items will be appended to
2008-03-02 16:06:57 +00:00
the existing root directory. Examine the options table below to force <command > mksquashfs </command> to overwrite the whole destination
and/or change the way new source items are added.
2008-07-25 16:20:47 +00:00
</para> </listitem>
2004-06-07 19:09:22 +00:00
2008-07-25 16:20:47 +00:00
<listitem > <para >
2004-03-02 14:33:32 +00:00
If a single source file or directory is given, it becomes the root in a newly created file system. If two
or more source files and/or directories are given, they will all become sub-items in the root of
the new file system.
2008-07-25 16:20:47 +00:00
</para> </listitem>
2004-06-07 19:09:22 +00:00
2008-07-25 16:20:47 +00:00
<listitem > <para >
2004-06-07 19:09:22 +00:00
The resulting filesystem will be padded to a multiple of 4 Kb: this
is required for filesystems to be used on block devices. If you are very sure
2008-07-25 16:20:47 +00:00
you don't ned this, use the <command > -nopad </command> option to disable this
2004-06-07 19:09:22 +00:00
operation.
2008-07-25 16:20:47 +00:00
</para> </listitem>
2004-06-07 19:09:22 +00:00
</itemizedlist>
2004-03-02 14:33:32 +00:00
</para>
<para >
2004-06-07 19:09:22 +00:00
See the next section for more details about all possible options.
2004-03-02 14:33:32 +00:00
</para>
</sect2>
<sect2 id= "mksqoptions" >
2004-06-07 19:09:22 +00:00
2004-03-02 14:33:32 +00:00
<title > Command-line options</title>
<para >
All possible options for <command > mksquashfs</command> are shown in the table below.
</para>
<table frame= "all" >
2004-06-07 19:09:22 +00:00
<title > Command-line options of the <command > mksquashfs</command> tool</title>
2004-03-02 14:33:32 +00:00
<tgroup cols= "2" >
<thead >
<row >
<entry > Option</entry>
<entry > Description</entry>
</row>
</thead>
<tbody >
2005-03-25 11:28:26 +00:00
<row >
2008-03-02 16:06:57 +00:00
<entry > <command > -2.0 </command> </entry>
2005-03-25 11:28:26 +00:00
<entry > force <command > mksquashfs</command> version 2.1 to create a version 2.0
filesystem</entry>
</row>
2004-11-10 09:24:10 +00:00
<row >
<entry > <command > -all-root</command> or <command > -root-owned</command> </entry>
<entry > make all files in the target file system owned by root (UID=0, GID=0)</entry>
</row>
2004-03-02 14:33:32 +00:00
<row >
2004-06-07 19:09:22 +00:00
<entry > <command > -always-use-fragments</command> </entry>
2008-03-02 16:06:57 +00:00
<entry > divide all files greater than block size into fragments (by the version 2.x).
It will result in greater compression ratios</entry>
2004-03-02 14:33:32 +00:00
</row>
<row >
2004-06-07 19:09:22 +00:00
<entry > <command > -b [block size]</command> </entry>
2008-03-02 16:06:57 +00:00
<entry > use [block size] filesystem block size (32 Kbytes default for 2.x, 128 kbytes for 3.x) - this can be either 4096, 8192, 16384, 32768, 65536 or 131072</entry>
2004-06-07 19:09:22 +00:00
</row>
<row >
<entry > <command > -be</command> or <command > -le</command> </entry>
<entry > force a big or little endian file system, respectively</entry>
2004-03-02 14:33:32 +00:00
</row>
2004-05-24 20:08:55 +00:00
<row >
2004-06-07 19:09:22 +00:00
<entry > <command > -check-data</command> </entry>
<entry > enable additional file system checks</entry>
</row>
<row >
<entry > <command > -e [file1] ( [file2] ... )</command> </entry>
2004-05-24 20:08:55 +00:00
<entry > specify which files and/or directories to omit
from the new file system that is to be created</entry>
</row>
<row >
2004-06-07 19:09:22 +00:00
<entry > <command > -ef [file]</command> </entry>
2004-05-24 20:08:55 +00:00
<entry > specify a <filename > file</filename> which contains the list of
files/directories to exclude</entry>
</row>
2004-11-10 09:24:10 +00:00
<row >
<entry > <command > -force-gid [GID]</command> </entry>
<entry > set all group IDs in target file system to [GID]
(can be specified as a name or a number)</entry>
</row>
<row >
<entry > <command > -force-uid [UID]</command> </entry>
<entry > set all user IDs in target file system to [UID]
(can be specified as a name or a number)</entry>
</row>
2004-05-24 20:08:55 +00:00
2004-03-02 14:33:32 +00:00
<row >
2004-06-07 19:09:22 +00:00
<entry > <command > -info</command> </entry>
<entry > print files, their original size and compression ratio, as they are added to
the file system</entry>
2004-03-02 14:33:32 +00:00
</row>
<row >
2004-06-07 19:09:22 +00:00
<entry > <command > -keep-as-directory</command> </entry>
<entry > if the source is a single directory, force this directory to be a subdirectory
of the root in the created file system</entry>
2004-03-02 14:33:32 +00:00
</row>
<row >
2004-06-07 19:09:22 +00:00
<entry > <command > -noappend</command> </entry>
<entry > if the destination file/device already contains a squashed file system,
overwrite it, rather than append the new data to an existing file system</entry>
2004-03-02 14:33:32 +00:00
</row>
<row >
2004-06-07 19:09:22 +00:00
<entry > <command > -no-duplicates</command> </entry>
<entry > do not detect/remove duplicate file names</entry>
2004-03-02 14:33:32 +00:00
</row>
2004-06-07 19:09:22 +00:00
2004-03-02 14:33:32 +00:00
<row >
2004-06-07 19:09:22 +00:00
<entry > <command > -noD</command> or <command > -noDataCompression</command> </entry>
<entry > do not compress the data</entry>
2004-03-02 14:33:32 +00:00
</row>
<row >
2004-06-07 19:09:22 +00:00
<entry > <command > -noF</command> or <command > -noFragmentCompression</command> </entry>
2008-03-02 16:06:57 +00:00
<entry > do not compress the fragments (avaliable by 2.x)</entry>
2004-03-02 14:33:32 +00:00
</row>
<row >
2004-06-07 19:09:22 +00:00
<entry > <command > -no-fragments</command> </entry>
2008-03-02 16:06:57 +00:00
<entry > do not generate fragment blocks (avaliable by 2.x, this will
2004-06-07 19:09:22 +00:00
produce almost the same filesystem as 1.x did)</entry>
2004-03-02 14:33:32 +00:00
</row>
<row >
2004-06-07 19:09:22 +00:00
<entry > <command > -noI</command> or <command > -noInodeCompression</command> </entry>
<entry > do not compress the inode table</entry>
</row>
<row >
<entry > <command > -nopad</command> </entry>
<entry > do not pad the resulting file system to a multiple of 4 KBytes</entry>
2004-03-02 14:33:32 +00:00
</row>
<row >
<entry > <command > -root-becomes [name]</command> </entry>
2004-06-07 19:09:22 +00:00
<entry > can be used while appending to a pre-existing squashed file system: it will make a new root,
and [name] directory will contain all pre-existing files/directories
2004-03-02 14:33:32 +00:00
</entry>
</row>
2004-06-07 19:09:22 +00:00
<row >
<entry > <command > -version</command> </entry>
2008-03-02 16:06:57 +00:00
<entry > print the version, copyright and license message
</entry>
</row>
<row >
<entry > <command > -recover [name]</command> </entry>
<entry > recover filesystem data using recovery file [name] (3.3)
</entry>
</row>
<row >
<entry > <command > -no-recovery</command> </entry>
<entry > don't create a recovery file (3.3).
</entry>
</row>
<row >
<entry > <command > -no-exports</command> </entry>
<entry > don't make avaliable file system to export via NFS (3.x)
</entry>
2004-06-07 19:09:22 +00:00
</row>
2008-03-02 16:06:57 +00:00
<row >
<entry > <command > -no-sparse</command> </entry>
<entry > don't check for sparse files (3.x)</entry>
</row>
<row >
<entry > <command > -processors [number]</command> </entry>
<entry > set the number of CPU to create file system. By default it will be used all avaliable processors (3.x)</entry>
</row>
<row >
<entry > <command > --read-queue [size]</command> </entry>
<entry > set input queue to [size] Mb. (Default is 64 Mb)(3.x)</entry>
</row>
<row >
<entry > <command > -write-queue [size]</command> </entry>
2008-07-25 16:20:47 +00:00
<entry > set output queue to [size] Mb (3.x)</entry>
2008-03-02 16:06:57 +00:00
</row>
<row >
<entry > <command > -sort [sort_file]</command> </entry>
<entry > sort files relating to priorities in [sort_file] (3.x)</entry>
</row>
<row >
<entry > <command > -wildcards</command> </entry>
<entry > enable the extended shell wildcards to exclude directories/files (to be used with -e)</entry>
</row>
<row >
<entry > <command > -regex</command> </entry>
<entry > enable to use POSIX regular expressions (3.3)</entry>
</row>
2004-03-02 14:33:32 +00:00
</tbody>
</tgroup>
</table>
<para >
2004-06-07 19:09:22 +00:00
In most cases, you should leave all compression/block options by default, as they allow
<command > mksquashfs</command> to achieve the best possible compression ratios.
2004-03-02 14:33:32 +00:00
</para>
</sect2>
2008-03-02 16:06:57 +00:00
<sect2 id= "unsquashing" >
<title > Using unsquashfs</title>
<para >
<command > unsquashfs</command> is the tool for extracting data from squashed
file systems. The general command-line format for <command > unsquashfs</command> is:
</para>
<programlisting >
unsquashfs [options] target [files/directories to extract]
</programlisting>
<itemizedlist >
2008-07-25 16:20:47 +00:00
<listitem > <para >
2008-03-02 16:06:57 +00:00
target is the squashed file system to extract.
2008-07-25 16:20:47 +00:00
</para> </listitem>
2008-03-02 16:06:57 +00:00
</itemizedlist>
<para >
Notes for <command > unsquashfs</command> behavior:
</para>
<itemizedlist >
2008-07-25 16:20:47 +00:00
<listitem > <para >
By not specifying any <emphasis > destination path</emphasis> , unsquashfs extracts the compressed file system in the
2008-03-02 16:06:57 +00:00
<emphasis > ./squashfs-root </emphasis> directory.
2008-07-25 16:20:47 +00:00
</para> </listitem>
2008-03-02 16:06:57 +00:00
2008-07-25 16:20:47 +00:00
<listitem > <para >
2008-03-02 16:06:57 +00:00
The tool does not extract a squashed file system on already exsisting directory
unless the <command > -f</command> option is specified.
2008-07-25 16:20:47 +00:00
</para> </listitem>
2008-03-02 16:06:57 +00:00
2008-07-25 16:20:47 +00:00
<listitem > <para >
2008-03-02 16:06:57 +00:00
You can specify on the command line, a multiple number of files/directories to extract and the items
to be extracted can be also be given in a file with <command > -e [file]</command> option.
2008-07-25 16:20:47 +00:00
</para> </listitem>
2008-03-02 16:06:57 +00:00
</itemizedlist>
<para >
All possible options for <command > unsquashfs</command> are shown in the table below.
</para>
<table frame= "all" >
<title > Command-line options of the <command > unsquashfs</command> tool</title>
<tgroup cols= "2" >
<thead >
<row >
<entry > Option</entry>
<entry > Description</entry>
</row>
</thead>
<tbody >
<row >
<entry > <command > -v[ersion] </command> </entry>
<entry > print the version, licence and copyright message
</entry>
</row>
<row >
<entry > <command > -i[nfo]</command> </entry>
<entry > print the files as they are extracted from the file system</entry>
</row>
<row >
<entry > <command > -l[ist]</command> </entry>
<entry > list the squashed file system without extracting files</entry>
</row>
<row >
<entry > <command > -li</command> </entry>
<entry > list files with theyr attributes as they are unsquashed (3.3)</entry>
</row>
<row >
<entry > <command > -ll</command> </entry>
<entry > list the squashed file system files with attributes without any extraction (3.3)</entry>
</row>
<row >
<entry > <command > -d[estination] path</command> </entry>
<entry > specify a destination path for unsquashed items</entry>
</row>
<row >
<entry > <command > -f[orce]</command> </entry>
<entry > if files exist overwrite them</entry>
</row>
<row >
<entry > <command > -s[tat]</command> </entry>
2008-07-25 16:20:47 +00:00
<entry > display file system's superblock informations (it can discover the file system version and the options used to compress it) (3.3)</entry>
2008-03-02 16:06:57 +00:00
</row>
<row >
2008-03-06 12:44:08 +00:00
<entry > <command > -e[f] [extract file]</command> </entry>
<entry > list of directories or files to extract (entries given one per line) (3.3)</entry>
2008-03-02 16:06:57 +00:00
</row>
<row >
2008-07-25 16:20:47 +00:00
<entry > <command > -r[egex]</command> </entry>
2008-03-06 12:44:08 +00:00
<entry > treat extract names as POSIX regular expressions (3.3)</entry>
2008-03-02 16:06:57 +00:00
</row>
</tbody>
</tgroup>
</table>
<para >
Note that by 3.x release you can extract 1.x and 2.x squashed file system too.
</para>
</sect2>
</sect1>