{"id":22475266,"url":"https://github.com/ecdye/zram-config","last_synced_at":"2025-05-15T18:11:36.724Z","repository":{"id":37803963,"uuid":"178130175","full_name":"ecdye/zram-config","owner":"ecdye","description":"A complete zram-config utility for swap, directories, and logs to reduce SD, NAND and eMMC block wear.","archived":false,"fork":false,"pushed_at":"2025-04-27T05:12:51.000Z","size":636,"stargazers_count":490,"open_issues_count":3,"forks_count":58,"subscribers_count":16,"default_branch":"main","last_synced_at":"2025-04-27T06:20:20.004Z","etag":null,"topics":["linux","overlayfs","raspberry-pi","zram"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ecdye.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2019-03-28T05:06:40.000Z","updated_at":"2025-04-16T09:00:11.000Z","dependencies_parsed_at":"2024-06-02T02:51:05.737Z","dependency_job_id":"2a638385-85bb-41f4-b2e0-e93bee1e5b76","html_url":"https://github.com/ecdye/zram-config","commit_stats":{"total_commits":303,"total_committers":6,"mean_commits":50.5,"dds":0.4620462046204621,"last_synced_commit":"c5643cf54c695abd2779da2a51e4bbedf6bdf331"},"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ecdye%2Fzram-config","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ecdye%2Fzram-config/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ecdye%2Fzram-config/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ecdye%2Fzram-config/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ecdye","download_url":"https://codeload.github.com/ecdye/zram-config/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254394726,"owners_count":22063984,"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":["linux","overlayfs","raspberry-pi","zram"],"created_at":"2024-12-06T13:14:54.349Z","updated_at":"2025-05-15T18:11:36.697Z","avatar_url":"https://github.com/ecdye.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# zram-config\n[![License](https://img.shields.io/github/license/ecdye/zram-config)](https://github.com/ecdye/zram-config/blob/main/LICENSE.md)\n[![ShellCheck](https://github.com/ecdye/zram-config/workflows/ShellCheck/badge.svg)](https://github.com/ecdye/zram-config/actions?query=workflow%3AShellCheck)\n[![Test](https://github.com/ecdye/zram-config/actions/workflows/test-action.yml/badge.svg)](https://github.com/ecdye/zram-config/actions/workflows/test-action.yml)\n\n## Overview\n\nThis is a complete zram-config utility for swap, directories, and logs to reduce SD, NAND and eMMC block wear.\nFurthermore zram allows near RAM speed access to working directories, and prevents frequent writing to persistent storage.\nEven more importantly, data stored in zram can be compressed to conserve memory.\n\nA table located at `/etc/ztab` is used to configure any number and type of zram devices.\nUsing the table an OverlayFS mount is used to mount the newly created zram device as the upper filesystem of the OverlayFS.\nOverlayFS is used so that files do not need to be copied from persistent storage to RAM on startup.\nIn theory this should allow for faster boots and larger directories as no complete directory copy is needed.\nA version of [kmxz/overlayfs-tools](https://github.com/kmxz/overlayfs-tools) is used to implement the OverlayFS sync logic.\n\nThis tool is primarily developed and tested against Raspberry Pi OS.\nAny Debian derivative should also work out of the box, however there is no guarantee.\nExperimental Alpine support has also been added, other distributions may work but once again, there is no guarantee.\n\n## A Brief Usage Guide\n\n### Install\n\nThe following assumes that you have the [`gh`](https://cli.github.com) cli tool installed and setup on your system.\n\n``` shell\ngh release download --repo ecdye/zram-config --pattern '*.tar.lz'\nmkdir -p zram-config \u0026\u0026 tar -xf zram-config*.tar.lz --strip-components=1 --directory=zram-config\nsudo ./zram-config/install.bash\n```\n\n#### Manually start or stop\n\nOn Debian, use `sudo systemctl {start|stop} zram-config.service` to start or stop zram-config.\nOn Alpine, use `sudo rc-service zram-config {start|stop}`.\nThis will ensure that any changes are properly synced to the persistent storage before system poweroff.\n\n#### Sync files to disk\n\nRun `sudo zram-config sync` to sync any changes in the zram filesystems managed by zram-config to persistent storage.\nIf you have concerns about losing data due to sudden power loss you could use this to ensure that changes are synced to disk periodically.\n\nA default sync service that will sync files to disk every night can be installed by running the following.\n\n``` shell\nsudo /path/to/zram-config/install.bash sync\n```\n\nNote that this sync service is not installed by default, you must install it separately.\n\n### Update\n\n``` shell\nsudo /path/to/zram-config/update.bash\n```\n\nTo make changes to the code or checkout a specific branch/tag and prevent it from updating/resetting all changes run the following instead.\n\n``` shell\nsudo /path/to/zram-config/update.bash custom\n```\n\n### Uninstall\n\n``` shell\nsudo /usr/local/share/zram-config/uninstall.bash\n```\n\n### Configure\n\nAll configuration is done in the `/etc/ztab` file.\n\nUse `#` to comment out any line, add new drives with the first column providing the drive type and then drive details separated by tab characters.\n\nAll algorithms in `/proc/crypto` are supported but only `lzo-rle`, `lzo`, `lz4`, and `zstd` have zramctl text strings; `lzo-rle` is the fastest with `zstd` having much better text compression.\n\n`mem_limit` is the compressed memory limit and will set a hard memory limit for the system admin.\nSet to 0 to disable the `mem_limit`.\n\n`disk_size` is the maximum size of the uncompressed memory.\nIt should be set to roughly 150% of `mem_limit` depending on the algorithm and how compressible the input files are.\nDon't make it much higher than the compression algorithm (and the additional zram overhead) is capable of because there is a ~0.1% memory overhead when empty.\n\n`swap_priority` will set zram over alternative swap devices.\n\n`page-cluster` 0 means tuning to singular pages rather than the default 3 which caches 8 for HDD tuning, which can lower latency.\n\n`swappiness` 150 because the improved performance of zram allows more usage without any adverse affects from the default of 60.\nIt can be raised up to 200 which will improve performance in high memory pressure situations.\n\n`target_dir` is the directory you wish to hold in zram, and the original will be moved to a bind mount and is synchronized on start, stop, and write commands.\n\n`oldlog_dir` will enable log-rotation to an off device directory while retaining only live logs in zram.\nUsually in `/opt` or `/var`, name optional.\n\nIf you need multiple zram swaps or zram directories, just create another entry in `/etc/ztab`.\nTo do this simply add the new entries to the `/etc/ztab`, if you need to edit an active zram device you must stop zram with `sudo systemctl stop zram-config.service` on Debian or `sudo rc-service zram-config stop` on Alpine and then edit any entries you need to.\nOnce finished, start zram using `sudo systemctl start zram-config.service` or `sudo rc-service zram-config start` which will only add the new entries if zram is already running.\n\n#### Example configuration\n\n```\n# swap\talg\t\tmem_limit\tdisk_size\tswap_priority\tpage-cluster\tswappiness\nswap\tlzo-rle\t\t250M\t\t750M\t\t75\t\t0\t\t150\n\n# dir\talg\t\tmem_limit\tdisk_size\ttarget_dir\n#dir\tlzo-rle\t\t50M\t\t150M\t\t/home/pi\n\n# log\talg\t\tmem_limit\tdisk_size\ttarget_dir\toldlog_dir\nlog\tlzo-rle\t\t50M\t\t150M\t\t/var/log\t/opt/zram/oldlog\n```\n\n### Is it working?\n\nRun `zramctl` in your preferred shell and if you see and output similar to below, yes it is working.\nPlease note that if the `zramctl` command is missing, you will need to install the `util-linux` package to have a convenient way to view the zram status.\n\n```\npi@raspberrypi:~$ zramctl\nNAME       ALGORITHM DISKSIZE  DATA  COMPR TOTAL STREAMS MOUNTPOINT\n/dev/zram1 lzo-rle       150M 16.9M 373.2K  692K       4 /opt/zram/zram1\n/dev/zram0 lzo-rle       750M    4K    87B   12K       4 [SWAP]\n```\n\nTo view more information on zram usage take a look at the following commands and their corresponding output.\n\n```\npi@raspberrypi:~$ df\nFilesystem     1K-blocks    Used Available Use% Mounted on\n/dev/root        3833792 1368488   2275172  38% /\ndevtmpfs          437356       0    437356   0% /dev\ntmpfs             471980       0    471980   0% /dev/shm\ntmpfs             188792     440    188352   1% /run\ntmpfs               5120       0      5120   0% /run/lock\n/dev/mmcblk0p1    258095   49436    208660  20% /boot\n/dev/zram1        132240   18440    103048  16% /opt/zram/zram1\noverlay1          132240   18440    103048  16% /var/log\ntmpfs              94396       0     94396   0% /run/user/1000\n```\n```\npi@raspberrypi:~$ free -h\n               total        used        free      shared  buff/cache   available\nMem:           921Mi        46Mi       750Mi       0.0Ki       124Mi       819Mi\nSwap:          849Mi          0B       849Mi\n```\n```\npi@raspberrypi:~$ swapon\nNAME       TYPE      SIZE USED PRIO\n/var/swap  file      100M   0B   -2\n/dev/zram0 partition 750M   0B   75\n```\n\n### Known issues\n\n#### Conflicts with services\n\nWhen running zram on a directory that has services accessing it, they will need to be stopped before starting or stopping zram.\nFor example, in the log zram device zram-config stops the services that run by default in the `/var/log` directory before starting or stopping.\nIf your system has other services that write to `/var/log` that are not stopped zram may fail to properly sync files and remove the zram device when stopping, and will probably outright fail to start when initializing a zram device.\nThis issue is not limited to logs, if you are running zram on another directoy that is written to by a service you will run into the same issue.\n\nFor an example on how this project internally takes care of this issue see the `serviceConfiguration` function in zram-config.\nA more in depth version of this function is used in the `openHAB` branch that can be referenced as well.\n\n#### Swapiness on older Linux kernel versions\n\nWhen running zram swap on Linux kernel versions older than 5.8 swappiness has a maximum value of 100.\nIf you observe issues runnning on older kernel versions try setting the default value of 150 back to 100.\n\n#### Raspberry Pi 4 8GB compatibility\n\nThe Raspberry Pi 4 8GB model can exhibit issues with zram due to a Linux kernel bug.\nThis bug has been fixed as of Raspberry Pi Kernel version 1.20210527.\nSee [raspberrypi/linux@cef3970381](https://github.com/raspberrypi/linux/commit/cef397038167ac15d085914493d6c86385773709) for more details about the issue.\n\n#### Filesystem compatibility\n\nBy default zram-config should support most regular filesystems, as long as the tools are installed and available on the host system.\nIn some cases, with niche filesystems some manual editing of the code may be required to enable support.\n\nPull requests adding support for filesystems that don't work automatically are welcome.\n\n#### Compatibility issues in virtual machines\n\nWhen running zram-config in a virtual machine (VM), you may encounter compatibility issues due to the differences in how VMs handle memory and storage compared to physical hardware.\nPerformance may vary, and certain features might not work as expected.\nIt is also common for VMs to not have implemented emulation in their kernel for zram.\nIf you experience issues, it may be better to not use zram-config in your VM environment.\nIt is recommended to thoroughly test zram-config in your specific VM setup to ensure it meets your needs.\n\n#### Removal of `bind_dir` in `ztab`\n\nOlder versions of zram-config included the option to manually configure a `bind_dir` in the `ztab`.\nThis functionality was removed in favor of automatically creating a bind mount as it is less confusing and more consistent with the rest of the code.\n\nChecks are in place to automatically convert `ztab` to this new format.\nIf errors occur, you may need to manually edit `ztab` to fix any issues.\n\n### Performance\n\nLZO-RLE offers the best performance and is probably the best choice, and from kernel 5.1 and onward it is the default.\nIf you are not running at least kernel 5.1 then LZO-RLE may not be supported by your system and you may need to change `/etc/ztab` accordingly.\nYou might have text based low impact directories such as `/var/log` or `/var/cache` where a highly effective text compressor such as zstd is optimal, with effective compression that can be up to 200% of what LZO may achieve especially with text.\nWith `/tmp` and `/run`, zram is unnecessary because they are RAM mounted as `tmpfs` and, if memory gets short, then the zram swap will provide extra.\nIt is only under intense loads that the slight overhead of zram compression becomes noticeable.\n\nThis chart in [facebook/zstd](https://github.com/facebook/zstd?tab=readme-ov-file#benchmarks) provides a good reference for the performance of the different compressors.\n\n### Reference\n\n\u003chttps://www.kernel.org/doc/Documentation/blockdev/zram.txt\u003e\n\n\u003chttps://www.kernel.org/doc/Documentation/filesystems/overlayfs.txt\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fecdye%2Fzram-config","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fecdye%2Fzram-config","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fecdye%2Fzram-config/lists"}