{"id":13560095,"url":"https://github.com/Vanilla-OS/ABRoot","last_synced_at":"2025-04-03T15:31:35.205Z","repository":{"id":63528822,"uuid":"566825585","full_name":"Vanilla-OS/ABRoot","owner":"Vanilla-OS","description":"ABRoot is utility which provides full immutability and atomicity to a Linux system, by transacting between two root filesystems. Updates are performed using OCI images, to ensure that the system is always in a consistent state.","archived":false,"fork":false,"pushed_at":"2024-04-29T22:31:28.000Z","size":14260,"stargazers_count":252,"open_issues_count":16,"forks_count":17,"subscribers_count":9,"default_branch":"main","last_synced_at":"2024-05-01T09:46:40.331Z","etag":null,"topics":["atomicity","command-line","hacktoberfest","immutability","linux","transactions","vanillaos"],"latest_commit_sha":null,"homepage":"http://abroot-dev.vanillaos.org/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Vanilla-OS.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"COPYING.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},"funding":{"github":"vanilla-os","liberapay":"fabricators"}},"created_at":"2022-11-16T13:58:15.000Z","updated_at":"2024-05-05T08:29:46.997Z","dependencies_parsed_at":"2023-12-20T15:33:15.905Z","dependency_job_id":"1ac8c74d-877b-4a60-9d64-21b25f549913","html_url":"https://github.com/Vanilla-OS/ABRoot","commit_stats":{"total_commits":213,"total_committers":6,"mean_commits":35.5,"dds":0.323943661971831,"last_synced_commit":"9864b9dc0259421c7778a38f7518646d40914346"},"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Vanilla-OS%2FABRoot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Vanilla-OS%2FABRoot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Vanilla-OS%2FABRoot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Vanilla-OS%2FABRoot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Vanilla-OS","download_url":"https://codeload.github.com/Vanilla-OS/ABRoot/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247027948,"owners_count":20871627,"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":["atomicity","command-line","hacktoberfest","immutability","linux","transactions","vanillaos"],"created_at":"2024-08-01T13:00:37.497Z","updated_at":"2025-04-03T15:31:30.194Z","avatar_url":"https://github.com/Vanilla-OS.png","language":"Go","readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"abroot-logo.svg\" height=\"120\"\u003e\n  \u003ch1 align=\"center\"\u003eABRoot v2\u003c/h1\u003e\n  \u003cp align=\"center\"\u003eABRoot is a utility that provides full immutability and\n    atomicity to a Linux system, by transacting between two root filesystems.\n    Updates are performed using OCI images, to ensure that the system is always\n    in a consistent state. It also allows for local atomic changes thanks to\n    the integrated ABRoot package manager, which generates local OCI images\n    with the user's changes, and then applies them on top of the system's\n    default image.\u003c/p\u003e\n\u003c/div\u003e\n\n## Help output\n\n```md\nABRoot provides full immutability and atomicity by performing transactions between 2 root partitions (A\u003c-\u003eB)\n\nUsage:\n  abroot [command]\n\nAvailable Commands:\n  completion  Generate the autocompletion script for the specified shell\n  help        Help about any command\n  kargs       Manage kernel parameters\n  pkg         Manage packages\n  rollback    Return the system to a previous state\n  status      Display status\n  upgrade     Update the boot partition\n\nFlags:\n  -h, --help      help for abroot\n  -v, --verbose   Show more detailed output\n      --version   version for abroot\n\nUse \"abroot [command] --help\" for more information about a command.\n```\n\n## Installation\n\nABRoot is a single binary, which can be placed anywhere on the system. It\nrequires administrative privileges to run and a configuration file to be\npresent in one of the following locations, ordered by priority:\n\n- `~/.config/abroot/abroot.json` -\u003e for user configuration\n- `config/abroot.json` -\u003e for development purposes only\n- `../config/abroot.json` -\u003e for development purposes only\n- `/etc/abroot/abroot.json` -\u003e for administrative configuration\n- `/usr/share/abroot/abroot.json` -\u003e for system-wide configuration\n\nThe configuration file is a JSON file with the following structure:\n\n```json\n{\n    \"autoRepair\": true,\n    \"maxParallelDownloads\": 2,\n\n    \"registry\": \"ghcr.io\",\n    \"registryService\": \"registry.ghcr.io\",\n    \"registryAPIVersion\": \"v2\",\n    \"name\": \"vanilla-os/desktop\",\n    \"tag\": \"main\",\n\n    \"iPkgMngPre\": \"lpkg --unlock\",\n    \"iPkgMngPost\": \"lpkg --lock\",\n    \"iPkgMngAdd\": \"apt install -y\",\n    \"iPkgMngRm\": \"apt remove -y\",\n    \"iPkgMngApi\": \"https://packages.vanillaos.org/api/pkg/{packageName}\",\n    \"iPkgMngStatus\": 0,\n\n    \"differURL\": \"https://differ.vanillaos.org\",\n\n    \"partLabelVar\": \"vos-var\",\n    \"partLabelA\": \"vos-a\",\n    \"partLabelB\": \"vos-b\",\n    \"partLabelBoot\": \"vos-boot\",\n    \"partLabelEfi\": \"vos-efi\",\n    \"PartCryptVar\": \"/dev/mapper/vos--var-var\",\n\n    \"thinProvisioning\": false,\n    \"thinInitVolume\": \"\",\n\n    \"libPathStates\": \"/var/lib/abroot/states\"\n}\n```\n\nThe following table describes each of the configuration options:\n\n| Option | Description |\n| --- | --- |\n| `autoRepair` | If set to `true`, ABRoot will automatically try to repair the system if a broken structure is detected during a transaction. |\n| `maxParallelDownloads` | The maximum number of parallel downloads to perform when updating the system. |\n| `registry` | The registry to use when pulling OCI images. |\n| `registryService` | The registry service to use when pulling OCI images. |\n| `registryAPIVersion` | The Docker Registry API version to use when pulling OCI images. (Only `v2` is tested) |\n| `name` | The name of the OCI image to use when pulling OCI images. |\n| `tag` | The tag of the OCI image to use when pulling OCI images. |\n| `iPkgMngPre` | The command to run before performing any package management operation. This is useful to keep the package manager locked outside of a transaction. It can be a command or a script. |\n| `iPkgMngPost` | Similar to `iPkgMngPre`, but runs after the package management operation. |\n| `iPkgMngAdd` | The command to run when adding a package. It can be a command or a script. |\n| `iPkgMngRm` | The command to run when removing a package. It can be a command or a script. |\n| `iPkgMngApi` | The API endpoint to use when querying for package information. If not set, ABRoot will not check if a package exists before installing it. This could lead to errors. Take a look at our [Eratosthenes API](https://github.com/Vanilla-OS/Eratosthenes/blob/388e6f724dcda94ee60964e7b12a78ad79fb8a40/eratosthenes.py#L52) for an example. |\n| `iPkgMngStatus` | The status of the package manager feature. The value '0' means that the feature is disabled, the value '1' means enabled and the value '2' means that it will require user agreement the first time it is used. If the feature is disabled, it will not appear in the commands list. |\n| `differURL` | The URL of the [Differ API](https://github.com/Vanilla-OS/Differ) service to use when comparing two OCI images. |\n| `partLabelVar` | The label of the partition dedicated to the system's `/var` directory. |\n| `partLabelA` | The label of the partition dedicated to the system's `A` root. |\n| `partLabelB` | The label of the partition dedicated to the system's `B` root. |\n| `partLabelBoot` | The label of the partition dedicated to the master boot. |\n| `partLabelEfi` | The label of the partition dedicated to the EFI boot. |\n| `PartCryptVar` | The encrypted partition to unlock during boot. On a non-lvm setup, this would be something like `/dev/nvme1n1p3`. |\n| `thinProvisioning` | If set to `true`, ABRoot will use and look for a thin provisioning setup. Check the section about [thin provisioning](#thin-provisioning) for more information. |\n| `thinInitVolume` | The init volume of the thin provisioning setup. |\n| `libPathStates` | NOT_IMPLEMENTED |\n\n## How it works\n\nABRoot works by performing transactions between two root partitions, `A` and `B`.\n\n### Terminology\n\n- **immutable** - a file or directory is immutable if it cannot be modified or\n  deleted by the user directly.\n- **transaction** - a transaction in this context is the process of updating\n  the system or applying changes to it.\n- **atomic** - a transaction is atomic if it is either fully applied or not\n  applied at all. There is no in-between state. This means that if a transaction\n  fails, the system will be kept in the same state as before the transaction\n  started, preventing the system from being left in an inconsistent state.\n\n### Boot process\n\nThe system manages those root partitions by assigning them the `current` or\n`future` roles. The `current` partition is the one that is currently being used\nby the system (runtime), while the `future` partition is the one that will be\nused after a successful transaction, by performing a reboot, and switching the\nroles of the partitions.\n\nThe boot process is composed of 2 entities:\n\n- **master boot** - the master boot is the first stage of the boot process. It\n  is responsible for loading the correct root-specific boot (GRUB config) and\n  the kernel (which is also root-specific).\n- **root-specific boot** - the root-specific boot is the second stage of the\n  boot process. It is responsible for loading the kernel modules and the kernel\n  parameters, and then booting the kernel.\n\nThe following schema shows how the boot process works:\n\n```txt\n+--------------------+    +--------------------+\n|                    |    |                    |\n|    Master Boot     | -\u003e | Root-specific Boot |\n|                    |    |                    |\n+--------------------+    +--------------------+\n                                   |\n                                   v\n+-------------------+    +---------------------+\n|                   |    |                     |\n|       System      | \u003c- |    Root-specific    |\n|                   |    |       Kernel        |\n+-------------------+    |                     |\n                         +---------------------+\n```\n\n### Transaction process\n\nThe transaction process is composed of multiple stages (11 at the time of\nwriting this). Each stage is responsible for performing a specific task, and\nthen passing the control to the next stage. Since ABRoot v2 is still in\ndevelopment, the transaction process could still change, so if you're\ninterested in the details, please check the source code for `ABSystem`, in the\n`core` package.\n\n## Thin provisioning\n\nABRoot supports (and suggests) thin provisioning, which allows for a more\nefficient use of disk space.\n\nLVM thin provisioning allows users to create virtual filesystems larger than\nthe available physical storage. This is possible due to LVM thin pools\nallocating blocks when they are written, rather than when a volume gets created.\nThin provisioning is commonly found in places like VPS clusters, where a\nprovider can allocate a very large storage pool (e.g. 500TB) without needing\nto have that amount of physical storage. This way, they can provide customers\nwith adequate storage limits and only buy more storage when it's actually\nneeded.\n\nThe following schema shows how an ABRoot-compatible disk layout would look like\nwith thin provisioning enabled:\n\n![Thin provisioning schema](assets/lvm-partitioning-structure.png)\n\nTo follow up, have a read at our [blog post](https://vanillaos.org/blog/article/2023-11-22/vanilla-os-orchid---devlog-22-nov)\nabout thin provisioning in ABRoot.\n","funding_links":["https://github.com/sponsors/vanilla-os","https://liberapay.com/fabricators"],"categories":["linux","Lower level tools"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FVanilla-OS%2FABRoot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FVanilla-OS%2FABRoot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FVanilla-OS%2FABRoot/lists"}