{"id":22366700,"url":"https://github.com/vaeth/squashmount","last_synced_at":"2025-07-30T17:32:18.816Z","repository":{"id":10119627,"uuid":"12188234","full_name":"vaeth/squashmount","owner":"vaeth","description":"Init and management script for mounting rewritable squashfs-compressed data","archived":false,"fork":false,"pushed_at":"2024-08-20T19:31:57.000Z","size":499,"stargazers_count":43,"open_issues_count":1,"forks_count":3,"subscribers_count":8,"default_branch":"main","last_synced_at":"2024-08-20T21:42:16.579Z","etag":null,"topics":["aufs","fuse","initscript","mounting","openrc","overlayfs","squashfs","systemd","unionfs","unionfs-fuse"],"latest_commit_sha":null,"homepage":null,"language":"Perl","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vaeth.png","metadata":{"files":{"readme":"README.md","changelog":"ChangeLog","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2013-08-18T00:53:55.000Z","updated_at":"2024-06-26T18:29:50.000Z","dependencies_parsed_at":"2022-09-06T02:50:11.731Z","dependency_job_id":null,"html_url":"https://github.com/vaeth/squashmount","commit_stats":null,"previous_names":[],"tags_count":104,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vaeth%2Fsquashmount","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vaeth%2Fsquashmount/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vaeth%2Fsquashmount/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vaeth%2Fsquashmount/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vaeth","download_url":"https://codeload.github.com/vaeth/squashmount/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":228164524,"owners_count":17879085,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aufs","fuse","initscript","mounting","openrc","overlayfs","squashfs","systemd","unionfs","unionfs-fuse"],"created_at":"2024-12-04T18:15:13.242Z","updated_at":"2024-12-04T18:15:13.920Z","avatar_url":"https://github.com/vaeth.png","language":"Perl","funding_links":[],"categories":[],"sub_categories":[],"readme":"# squashmount\n\n(C) Martin Väth (martin at mvath.de)\n\nThis project is under the BSD license 2.0 (“3-clause BSD license”).\nSPDX-License-Identifier: BSD-3-Clause\n\nInit and management script for mounting rewritable squashfs-compressed data\n\nThis is the successor of the __squash_dir__ project\n-\thttps://github.com/vaeth/squash_dir/\n\nIt is actually a ground-up rewrite of that project in perl with a\nhighly improved control interface.\n\nOne of its aims is to be init system independent.\nFor openrc and systemd ready-to-use init/service-files are provided;\nI gladly add init-files for other init systems if I receive (tested) patches.\n\n__squashmount__ works with systemd in “standard” setups, but due to\nconceptional bugs of systemd in some setups (see section “Installation”),\nsystemd is no longer officially supported.\n\n## What is this project?\n\nThis is __squashmount__, a generic initscript, user interface and management\ntool for keeping directories compressed by squashfs but simultaneously keep\nthem writable using some of (depending on the configuration and what is\navailable):\n\n-\toverlay (AKA overlayfs for linux kernels 3.18 and newer)\n-\toverlayfs, a variant for older linux kernels, see\n\t\thttp://git.kernel.org/?p=linux/kernel/git/mszeredi/vfs.git\n-\taufs, see http://aufs.sourceforge.net\n-\tfuse-overlayfs, see https://github.com/containers/fuse-overlayfs\n-\tunionfs-fuse, see http://podgorny.cz/moin/UnionFsFuse\n\t\t(unionfs-fuse-0.25 or newer is required)\n-\tunionfs, see http://www.fsl.cs.sunysb.edu/project-unionfs.html\n-\tfunionfs, see http://bugs.gentoo.org/show_bug.cgi?id=151673\n\nSince __squashmount v15.0.0__ there is also a choice between\n\n-\tsquashfs (the linux kernel module)\n-\tsquashfuse, the fuse module, see https://github.com/vasi/squashfuse\n\nThe idea is that, as a rule, on shutdown the data is recompressed\n(and the temporary modified data removed).\nThis approach is originally due to synss' script from\n\thttp://forums.gentoo.org/viewtopic-t-465367-highlight-.html\nIn that forum thread you can also ask for help about this project.\n\nFor some mount points different rules than “resquash and delete on umount”\nmight be desired (see the examples section below), and moreover,\nit might be necessary to override these rules temporarily.\nFor such things a powerful user interface is provided.\n\nThis project can be useful for any linux distribution.\nHistorically, the main motivations was to keep the Gentoo main repository\ncompressed. This is still one of the most striking examples:\n\nIf the Gentoo main repository (`/usr/portage` or `/var/db/repos/gentoo`)\nis compressed with __squashmount__ (without `DISTDIR` which you should store\nsomewhere else when using this script), the required disk space is only\nabout 50-100 MB (depending on your compression method), instead of\n200-400 MB (or much higher, the actual space requirement\ndepending essentially on the filesystem, e.g. how inodes are used).\nUsually, also the access is much faster.\n\nIt is possible to combine __squashmount__ with portage's\n`sync-type = squashdelta` to mount the Gentoo repository writable.\n\n## Screenshot with a typical usage\n\n![Demo screenshot](demo.svg?sanitize=true)\n\n## Requirements\n\nThe script requires of course that squashfs support is activated in the\nkernel (and supports the COMPRESSION method), that the mksquashfs tool\nis available, and also that some of the above mentioned unionfs-type tools\nis available and supported by the kernel.\n\n## Warning\n\nSince v17.0.0/v10.0.0 , __squashmount__ defaults to the COMPRESSION method\n`zstd`/`lz4`. This method is available only in linux-4.14/3.19 or higher\nor in squashfuse-0.1.101_alpha20170917/0.1.100_alpha20140523 or higher.\nSo take care to either use a sufficiently new kernel/squashfuse version\nor to change the default!\n\nMoreover, you need a decently new version of _perl5_ together with some of\nits standard modules (which might need to be installed separately if your\n_perl5_ version should be too old). Decently new perl versions should have the\n`TERM::ANSIColor` module; you need this if you want to see nicely\ncolored output.\n\nIt is also strongly recommended to install the `File::Which` module\n(although there are some fallbacks if it is not available).\n\nIf you want that the hard status line is set, also the title script from\nhttps://github.com/vaeth/runtitle (version \u003e=2.3) is required in your path.\n\n\n## Installation\n\nIf you are a Gentoo user, you can just emerge __squashmount__ from the\n__mv overlay__.\n\nOtherwise you just have to copy `bin/squashmount` into `/usr/bin/squashmount`\nor any other directory of your `$PATH`.\nFor zsh completion support also copy `zsh/_squashmount` into a directory of\nyour zsh's `$fpath`.\n\nIt is strongly recommended to put\n-\t`alias squashmount='noglob squashmount'`\n\ninto your `~/.zshrc` or `/etc/zsh/zshrc` or `/etc/zshrc`,\nso that things like\n-\t`squashmount start *`\n\nwill work in your zsh as intended without the need to quote *.\n(I assume that you do not use any poor shell instead of zsh.) ;)\n\nIf you use __revdep-rebuild__ from Gentoo or similar distributions, and\nif you use the default naming scheme, it is recommended to copy the content of\n`etc/revdep-rebuild` into `/etc/revdep-rebuild` to cancel duplicate or obsolete\npaths search of revdep-rebuild.\n\nFor __openrc__ support copy `openrc/init.d/squashmount` to\n`/etc/init.d/squashmount` and activate it in the usual way.\nFor systemd-support copy `systemd/system/squashmount.service` to your\nsystemd unit folder (`pkg-config --variable=systemdsystemunitdir systemd`,\nusually `/lib/systemd/system` or `/usr/lib/systemd/system`)\nand activate it in the usual way (or e.g. copy into `/etc/systemd/system`)\n\nIf you use __systemd__ _be sure to compile the __mount__ binary\nwith __systemd__ support_\n(this should be the case in most distributions providing systemd; in Gentoo\nthis means to enable `USE=systemd` for the util-linux package. If you compile\nutil-linux manually, make sure to pass `--with-systemd` to `./configure`).\nIn this case, __systemd__ will probably work for you in “standard” setups.\nWith __systemd-219__ (or newer?) and some unusual setups like `--make-shared`\non some partitions, it can happen nevertheless that __mount__ appears to work,\nbut actually nothing is mounted if __systemd__ is in use. This is related with\nthe fact that __systemd__ tries to control all mounts instead of letting the\nkernel do it alone. Of course, this breaks tools like __squashmount__\ncompletely.\nBug __systemd__ upstream about such problems, but not me: I am not planning\nto add hacks to fix the breakage introduced by some ill-conceived __systemd__\nconcepts.\n\nFor __systemd__, you should set an appropriate timeout: There is no general\nrule how long compression can take “maximally”, so the timeout is set to\ninfinity, by default. It is strongly recommended to set this to a realistic\nvalue for you system and setting by giving a (generous) upper estimate for\nyour needs by copying the file `etc/system/squashmount.service.d/timeout.conf`\nto `/etc/systemd/squashmount/service.d/timeout.conf` and editing appropriately.\nIf you copied the main script not to `/usr/bin/squashmount`, you should\nput into the same directory a file with appropriate modified paths.\nFor instance, if you copied the main script to `/sbin/squashmount` then\ncreate `/etc/systemd/system/squashmount.service.d/exec.conf` with the content\n```\n[Service]\nExecStart=\nExecStart=/sbin/squashmount start\nExecStop=\nExecStop=/sbin/squashmount -f --lsof=0 stop\n```\nAlso copy `tmpfiles.d/squashmount.conf` to `/usr/lib/tmpfiles.d`, although this\nis not absolutely necessary (squashmount will create the corresponding\ndirectories anyway).\nIf you use an init-system which does not mount /run as a ramdisk,\nyou should cleanup /run/squashmount on every fresh start before\ncalling `squashmount start`.\nDepending on your init-system, a way to achieve this might be to change the\nfirst letter in the crucial line in `/usr/lib/tmpfiles.d/squashmount.conf`\nfrom `d` to `D!` and to make sure that the processing of `/usr/lib/tmpfiles.d`\ntakes place before calling `squashmount start`.\n(Since accidental cleaning can have very inconvenient consequences, and\ncurrently only systemd supports the `D!` syntax, `d` is the default.)\nSee section __Emergency Case__ what to do if `/run/squashmount`\nis removed accidentally anyway.\nIf you use `find_cruft`, you might want to copy the content of\n`lib/find_cruft` to `/usr/lib/find_cruft` or `/etc` and adapt it to your needs.\n\nIf you plan to use portage's `sync-type = squashdelta`, you might want to copy\nthe content of `etc/portage/repo.postsync.d` to `/etc/portage/repo.postsync.d`\nNote that the hook-file in this directory treats the mount point “gentoo”\nspecially! See the example configuration in `etc/squashmount.pl` how to\nsetup an appropriate mount point “gentoo” for this setting.\n\nIn all cases you have to copy `lib/squashmount.pl` to `/etc/squashmount.pl`\nand adapt it to your need! This is an essential point of squashmount,\nand it is impossible to use squashmount without setting up the configuration.\nYou can optionally also copy `lib/squashmount.pl` to `/lib/squashmount.pl` or\n`/usr/lib/squashmount.pl` to provide a system-wide example config.\nAlternatively, you can also modify that file to use it as a fallback if\n`/etc/squashmount.pl` is not readable.\n\n\n## Some Examples\n\nEssentially, the init-system (or you) has to call\n-\t`squashmount start`\n\non start and\n-\t`squashmount -f --lsof=0 stop`\n\non shutdown (at a time when the local filesystems are already/still mounted).\nThe provided installation files for systemd and openrc do just this.\n\nThis will cause all configured mount points to be mounted/umounted\ncorrespondingly. When umounting, by default the modified data is\nrecompressed into the squash-files (but this can be customized).\n\nThe configuration of the mount points happens in the file /etc/squashmount.pl\nThis is a perl file, so you can use perl code in this file to source other\nfiles at your discretion.\n\nThe provided example configuration file etc/squashmount.pl is rather\nrealistic if you are a Gentoo user: It provides the following mount points\n\n- (a)  guest:    A guest user's home directory /home/guest\n- (b)  tex:      The installed files from texlive /usr/share/texmf-dist\n- (c1) portage:  The Gentoo repository /usr/portage\n- (c2) gentoo:   The Gentoo repository when using sync-type = squashdelta\n- (d)  db:       The Gentoo database of installed packages /var/db\n\nFurther mount points are in the example config-file but not listed here.\n\nFor all the mount points it is reasonable to use squashmount with them for\ndifferent reasons:\n\n- (a) The guest-user should be able to modify data in /home/guest, but its\nchanges should usually be forgotten. (Sometimes you will not want to\nforget these changes, e.g. when you want to update the “default”\nhome directory which the user sees; see below how to do this).\n\n- (b) The tex directory is huge, and it saves considerable space to keep it\ncompressed on disk.\n\n- (c1) Keeping the Gentoo repository compressed does not only save an enormous\namount of disk space but actually also speeds up portage considerable,\nbecause the disk access is faster on a single (squashed) file.\nMoreover, after changes with eix --sync you might want to compare the\nnew files with previous versions in the squashed file which you can still\naccess when you use squashmount.\n\n- (c2) When you prefer to use portage's `sync-type = squashdelta`, you already\nhave the advantage of a compressed portage tree. However, you might want to\nuse squashmount to make this portage tree writable (e.g. in order to\ntemporarily fix a broken Manifest file locally).\n\n- (d) The db directory is short but its data is very sensible and the\nnumber files is huge: Keeping it in a compressed file gives a lot\nof disk space and speedup, and it makes sense to keep a compressed backup\nof the last mounted version.\n\nIn these examples, additional features of squashmount are used in\nthe example configuration:\n\n1. For (a), it is obviously necessary to use a different treatment:\nNormally, the squash-file should not be generated, and the temporary data\nshould be removed.\nA similar remark holds for (c2).\n\n2. For (d), squashmount will keep a backup even of the squash-file for\nthe db directory.\n\n3. squashing of (c1) and (d) should happen only when a certain\nthreshold of changes to the data is reached.\nThe modified data will survive the reboot even if it is not resquashed,\nbut it takes more diskspace of course, and there is no readonly version of\nthe corresponding files.\n\n4. No resquash of the tex directory when only certain files (like the\nautomatically generated `ls-R` file) were updated:\nIn fact, if the only changes made to the directoy are in these files\n(it is optionally also checked that their content is not changed),\nthe directory will be cleared when umounting/remounting/rebooting.\n\nYou can also call squashmount at runtime to resquash or clean certain\ndirectories manually or to change states for the above “default” actions\non future umounts. For instance, if you changed the skeleton of the\nguest user in (a) you can call\n-\t`squashmount --no-kill remount guest`\n\nto force immediate regeneration of the squashed file from the directory.\nMoreover, you can call squashmount to temporarily change the state of mounted\ndirectories. For example, if you want to change temporarily that the guest\nuser's data is saved on remount, use\n-\t`squashmount --no-kill set guest`\n\nA changed state will remain active until reset, restart, or stop is executed.\nAnother example: If a lot of data would be resquashed at the next umount,\nbut you want to reboot urgently, just call\n-\t`squashmount --no-squash set`\n\nbefore rebooting.\nConversely, if you want to squash the portage mount point despite its\nthreshold is not reached (e.g. because you plan to make an experimental\nchange which you plan to undo later), you can call\n-\t`squashmount --squash restart portage`\n\nIf afterwards you made your experimental change and want to undo it, call\n-\t`squashmount --kill restart portage`\n\nIf your changes take a longer time and you want to make sure that you do not\nforget to call the above command, you can temporarily change the state:\n-\t`squashmount --kill set portage`\n\nNormally, this setting will survive a remount. In order to reset to the\noriginal setting after remounting, use option `-r` with `remount`:\n-\t`squashmount -r remount portage`\n\nThis is the same as calling\n-\t```\n\tsquashmount remount portage\n\tsquashmount reset portage\n\t```\n\nThe above examples should perhaps be enough to give you an impression how\nto use __squashmount__. To get an exact description of the user interface and\nof the config file format just execute:\n-\t`squashmount man`\n\n\n## Emergency Case\n\nIf you accidentally removed or corrupted `/run/squashmount`, e.g. due to a bug\nin squashmount itself or in its configuration or if the init-system was\nmisconfigured and removed /run/squashmount after calling `squashmount start`,\nyou should try to umount unconditionally.\nYou can instruct squashmount to do this with\n-\t`squashmount -fI umount`\n\nor (if you do not want resquashing in such a situation):\n-\t`squashmount -nfI umount`\n\nThis will work reliably unless you used temporary directories in your setup.\nIt will even work with temporary directories if their name is still stored\nin /run/squashmount, i.e. if the information there was not lost completely.\n\n\n## A Word of None-Warning\n\nIt is in general rather safe to squash a directory, even a rather vital one:\nEven if e.g. you boot from a kernel which has no support for some of\n__overlay__|__overlayfs__|__aufs__|__unionfs-fuse__|__unionfs__ |__funionfs__\nto make the directory writable, __squashmount__ will mount it at least as\nread-only (using `mount --bind` if necessary).\nMoreover, if everything goes wrong you can still use the __unsquashfs__ tool\nto unpack the directory manually.\nProbably the only danger in packing “strange” directories are special files,\nhard links (this information will usually get lost), or special devices\nwhich are perhaps not supported by the used tools.\n\n\n## Modules and Mounting\n\nSince version 3.0, unless configured otherwise, __squashmount__ will attempt\nto modprobe the modules\n-\tsquashfs\n-\taufs\n-\tfuse\n-\toverlay\n-\toverlayfs\n-\tunionfs\n\nwhen they are required; optionally/alternatively, also the corresponding\nkernel option can be checked in `/sys/module` or `/proc/config.gz`;\nalso the existence of required binaries can be checked before actually\nthe mounting is attempted.\nIt depends on your setting whether this is done and/or whether in case\nof failure the corresponding tool is skipped tacitly without attempting\nto mount.\n\nIf no tool mounts successfully, it is attempted to use `mount --bind` to get\nthe directory at least readonly on the expected place, so even in\nthis bad situation (which probably only happens if you boot from an\nexperimental kernel or a brand new kernel without corresponding support)\nyou can still access the directory read-only. Hence, also rather vital\ndirectories can be compressed as long as it is not vital to write to them\n(and as long as the relevant programs for mounting etc. are not contained\nwithin these directories, of course).\n\n\n## User Permissions\n\nIf you rely only on the tool squashfuse and either unionfs-fuse or funionfs\n(which are all based on the fuse userspace file system), then\nsquashmount can also be used with user permissions.\nTo support selecting only these tools and appropriate files and dirs from\nthe calling user, the option `--user` is supported since squashmount v15.0.0.\nFor details, call `squashmount man` and look for the option --user.\n\n\n## Recent squashfs-tools\n\nIt is recommended to use a new version than 4.3 of squashfs-tools which\nhas the `-quiet` option. Cf. the description of `--mksquash-verbose`\nand the `$mksquash_verbose` variable in `./squashmount man` for details.\nAs a Gentoo user you can install such a recent version from the mv overlay.\n\nHowever, this recommendation is only an eye-candy: `squashmount` will work\nwithout any problems also with an unpatched version of `squashfs-tools`;\njust the display when squashing will not be so nice.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvaeth%2Fsquashmount","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvaeth%2Fsquashmount","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvaeth%2Fsquashmount/lists"}