# SwapDog
SwapDog is a *swap watchdog* that monitors RAM usage and enables swap devices only when necessary, based on user-defined thresholds. It is designed to prevent excessive swapping, which can lead to performance degradation, while still allowing the system to function without crashing when RAM is exhausted.
### Rationale
It is meant to be useful when one doesn't want to swap memory if not strictly needed, but also doesn't want crashes.
- swap memory is always slower than RAM, especially HDDs are
- SSDs wears out with read and write cycles, while RAM doesn't
These reasons are enough for me to want to limit the usage of swap in a more radical way than [swappiness](https://askubuntu.com/a/157809/1559059) does.
## Installation
Any installation method assumes that you have access to the `swapdog.py`, `swapdog.json`, `requirements.txt` and `swapdog.service` files in the current directory.
```bash
git clone https://github.com/FLAK-ZOSO/SwapDog
cd SwapDog
```
You may want to proceed with the [configuration](#configuration) before installing, but you can also do it later.
### Automated
You can use the provided [install.sh](install.sh) script to automate the installation process. Just run the following command:
```bash
chmod +x install.sh
./install.sh
```
### Manual
Take this as a documentation of the steps that the `install.sh` script performs, so you can do it manually if you prefer:
1. Install dependencies with `sudo pip3 install -r requirements.txt`
2. Copy the [swapdog.py](swapdog.py) file to `/usr/local/sbin/`
3. Make it executable with `sudo chmod 744 /usr/local/sbin/swapdog.py`
4. Copy the [swapdog.json](swapdog.json) file to `/etc/`
5. Copy the [swapdog.service](swapdog.service) file to `/etc/systemd/system/`
6. Enable the service with `sudo systemctl enable swapdog`
7. Start the service with `sudo systemctl start swapdog`
8. Check the status of the service with `sudo systemctl status swapdog`
```bash
sudo pip3 install -r requirements.txt
sudo cp swapdog.py /usr/local/sbin/
sudo chmod 744 /usr/local/sbin/swapdog.py
sudo cp swapdog.json /etc/
sudo cp swapdog.service /etc/systemd/system/
sudo systemctl enable swapdog
sudo systemctl start swapdog
sudo systemctl status swapdog
```
## Configuration
In order to configure the behavior of SwapDog, you need to edit the `swapdog.json` file located in `/etc/`. The file follows a simple JSON structure that allows you to set thresholds and the swap devices to be used.
### Fields
- `thresholds`: An array of objects, each representing a threshold for enabling a swap device.
- `percentage`: The percentage of RAM usage that triggers the swap device to be enabled.
- `swap`: The path to the swap device (e.g., `/dev/sda1` or `/swapfile`).
- `period`: The time in seconds between checks of the RAM usage. Default is `1.0` seconds if not specified.
### How to configure
- Enable all swaps in order to make them easily detectable.
```bash
sudo swapon --all
```
- List the currently enabled swap devices.
```bash
sudo swapon --show
sudo cat /proc/swaps
```
What follows is an example output. You are looking for the `NAME` column to identify the swap devices.
```bash
NAME TYPE SIZE USED PRIO
/dev/dm-1 partition 7.4G 0B -2
/swapfile file 2.0G 0B -3
```
- Edit the `swapdog.json` file to set the desired thresholds and swap devices. For example, if you want to enable a swap device when RAM usage exceeds 95%, you can set it like this:
```json
{
"thresholds": [
{
"percentage": 95.0,
"swap": "/dev/dm-1"
},
{
"percentage": 90.0,
"swap": "/swapfile"
}
],
"period": 1.0
}
```
## Uninstallation
To uninstall SwapDog, you can use the provided [uninstall.sh](uninstall.sh) script or perform the steps manually.
### Automated
You can run the following command to uninstall SwapDog using the script:
```bash
chmod +x uninstall.sh
./uninstall.sh
```
### Manual
Take this as a documentation of the steps that the `uninstall.sh` script performs, so you can do it manually if you prefer:
1. Stop the service with `sudo systemctl stop swapdog`
2. Disable the service with `sudo systemctl disable swapdog`
3. Remove the service file with `sudo rm /etc/systemd/system/swapdog.service`
4. Remove the script with `sudo rm /usr/local/sbin/swapdog.py`
5. Remove the configuration file with `sudo rm /etc/swapdog.json`
```bash
sudo systemctl stop swapdog
sudo systemctl disable swapdog
sudo rm /etc/systemd/system/swapdog.service /usr/local/sbin/swapdog.py /etc/swapdog.json
sudo systemctl daemon-reload
```
Raw data
{
"_id": null,
"home_page": null,
"name": "swapdog",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "daemon, memory, monitoring, ram, swap",
"author": null,
"author_email": "FLAK-ZOSO <mattia.marchese.2006@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/58/35/5f522bd32735cb3e5ce9944d719ea678e98b6e38585bab78498c921788b8/swapdog-0.2.0.tar.gz",
"platform": null,
"description": "# SwapDog\n\nSwapDog is a *swap watchdog* that monitors RAM usage and enables swap devices only when necessary, based on user-defined thresholds. It is designed to prevent excessive swapping, which can lead to performance degradation, while still allowing the system to function without crashing when RAM is exhausted.\n\n### Rationale\n\nIt is meant to be useful when one doesn't want to swap memory if not strictly needed, but also doesn't want crashes.\n\n- swap memory is always slower than RAM, especially HDDs are\n- SSDs wears out with read and write cycles, while RAM doesn't\n\nThese reasons are enough for me to want to limit the usage of swap in a more radical way than [swappiness](https://askubuntu.com/a/157809/1559059) does.\n\n## Installation\n\nAny installation method assumes that you have access to the `swapdog.py`, `swapdog.json`, `requirements.txt` and `swapdog.service` files in the current directory.\n\n```bash\ngit clone https://github.com/FLAK-ZOSO/SwapDog\ncd SwapDog\n```\n\nYou may want to proceed with the [configuration](#configuration) before installing, but you can also do it later.\n\n### Automated\n\nYou can use the provided [install.sh](install.sh) script to automate the installation process. Just run the following command:\n\n```bash\nchmod +x install.sh\n./install.sh\n```\n\n### Manual\n\nTake this as a documentation of the steps that the `install.sh` script performs, so you can do it manually if you prefer:\n\n1. Install dependencies with `sudo pip3 install -r requirements.txt`\n2. Copy the [swapdog.py](swapdog.py) file to `/usr/local/sbin/`\n3. Make it executable with `sudo chmod 744 /usr/local/sbin/swapdog.py`\n4. Copy the [swapdog.json](swapdog.json) file to `/etc/`\n5. Copy the [swapdog.service](swapdog.service) file to `/etc/systemd/system/`\n6. Enable the service with `sudo systemctl enable swapdog`\n7. Start the service with `sudo systemctl start swapdog`\n8. Check the status of the service with `sudo systemctl status swapdog`\n\n```bash\nsudo pip3 install -r requirements.txt\nsudo cp swapdog.py /usr/local/sbin/\nsudo chmod 744 /usr/local/sbin/swapdog.py\nsudo cp swapdog.json /etc/\nsudo cp swapdog.service /etc/systemd/system/\nsudo systemctl enable swapdog\nsudo systemctl start swapdog\nsudo systemctl status swapdog\n```\n\n## Configuration\n\nIn order to configure the behavior of SwapDog, you need to edit the `swapdog.json` file located in `/etc/`. The file follows a simple JSON structure that allows you to set thresholds and the swap devices to be used.\n\n### Fields\n\n- `thresholds`: An array of objects, each representing a threshold for enabling a swap device.\n - `percentage`: The percentage of RAM usage that triggers the swap device to be enabled.\n - `swap`: The path to the swap device (e.g., `/dev/sda1` or `/swapfile`).\n- `period`: The time in seconds between checks of the RAM usage. Default is `1.0` seconds if not specified.\n\n### How to configure\n\n- Enable all swaps in order to make them easily detectable.\n\n```bash\nsudo swapon --all\n```\n\n- List the currently enabled swap devices.\n\n```bash\nsudo swapon --show\nsudo cat /proc/swaps\n```\n\nWhat follows is an example output. You are looking for the `NAME` column to identify the swap devices.\n\n```bash\nNAME TYPE SIZE USED PRIO\n/dev/dm-1 partition 7.4G 0B -2\n/swapfile file 2.0G 0B -3\n```\n\n- Edit the `swapdog.json` file to set the desired thresholds and swap devices. For example, if you want to enable a swap device when RAM usage exceeds 95%, you can set it like this:\n\n```json\n{\n \"thresholds\": [\n {\n \"percentage\": 95.0,\n \"swap\": \"/dev/dm-1\"\n },\n {\n \"percentage\": 90.0,\n \"swap\": \"/swapfile\"\n }\n ],\n \"period\": 1.0\n}\n```\n\n## Uninstallation\n\nTo uninstall SwapDog, you can use the provided [uninstall.sh](uninstall.sh) script or perform the steps manually.\n\n### Automated\n\nYou can run the following command to uninstall SwapDog using the script:\n\n```bash\nchmod +x uninstall.sh\n./uninstall.sh\n```\n\n### Manual\n\nTake this as a documentation of the steps that the `uninstall.sh` script performs, so you can do it manually if you prefer:\n\n1. Stop the service with `sudo systemctl stop swapdog`\n2. Disable the service with `sudo systemctl disable swapdog`\n3. Remove the service file with `sudo rm /etc/systemd/system/swapdog.service`\n4. Remove the script with `sudo rm /usr/local/sbin/swapdog.py`\n5. Remove the configuration file with `sudo rm /etc/swapdog.json`\n\n```bash\nsudo systemctl stop swapdog\nsudo systemctl disable swapdog\nsudo rm /etc/systemd/system/swapdog.service /usr/local/sbin/swapdog.py /etc/swapdog.json\nsudo systemctl daemon-reload\n```\n",
"bugtrack_url": null,
"license": "GNU General Public License v3.0 only",
"summary": "Monitors RAM usage and enables swap devices",
"version": "0.2.0",
"project_urls": {
"Changelog": "https://github.com/FLAK-ZOSO/SwapDog/blob/main/CHANGELOG.md",
"Issues": "https://github.com/FLAK-ZOSO/SwapDog/issues",
"Repository": "https://github.com/FLAK-ZOSO/SwapDog.git"
},
"split_keywords": [
"daemon",
" memory",
" monitoring",
" ram",
" swap"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "5f0860258081b9ee9236151fa90a60b61256d24925678802c34e9c454ec92565",
"md5": "7681208042b6b56e41c13edd04e2143d",
"sha256": "31c1c93b5adea8ae2ae5ef54da3a420a3e4e39e24f73bbe72ec753d2d3e0c259"
},
"downloads": -1,
"filename": "swapdog-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7681208042b6b56e41c13edd04e2143d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 17860,
"upload_time": "2025-08-20T12:26:43",
"upload_time_iso_8601": "2025-08-20T12:26:43.306481Z",
"url": "https://files.pythonhosted.org/packages/5f/08/60258081b9ee9236151fa90a60b61256d24925678802c34e9c454ec92565/swapdog-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "58355f522bd32735cb3e5ce9944d719ea678e98b6e38585bab78498c921788b8",
"md5": "20ada35227ad352b384f5488c6a13e81",
"sha256": "b840139a3ae2a83f70bb5b658b8502faa57cd58e6c0da293c9aadd87f1dbc215"
},
"downloads": -1,
"filename": "swapdog-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "20ada35227ad352b384f5488c6a13e81",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 19052,
"upload_time": "2025-08-20T12:26:44",
"upload_time_iso_8601": "2025-08-20T12:26:44.510191Z",
"url": "https://files.pythonhosted.org/packages/58/35/5f522bd32735cb3e5ce9944d719ea678e98b6e38585bab78498c921788b8/swapdog-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-20 12:26:44",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "FLAK-ZOSO",
"github_project": "SwapDog",
"github_not_found": true,
"lcname": "swapdog"
}
JSON
