You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The following table describes each of the configuration options:
88
+
89
+
| Option | Description |
90
+
| --- | --- |
91
+
|`autoRepair`| If set to `true`, ABRoot will automatically try to repair the system if a broken structure is detected during a transaction. |
92
+
|`maxParallelDownloads`| The maximum number of parallel downloads to perform when updating the system. |
93
+
|`registry`| The registry to use when pulling OCI images. |
94
+
|`registryService`| The registry service to use when pulling OCI images. |
95
+
|`registryAPIVersion`| The Docker Registry API version to use when pulling OCI images. (Only `v2` is tested) |
96
+
|`name`| The name of the OCI image to use when pulling OCI images. |
97
+
|`tag`| The tag of the OCI image to use when pulling OCI images. |
98
+
|`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. |
99
+
|`iPkgMngPost`| Similar to `iPkgMngPre`, but runs after the package management operation. |
100
+
|`iPkgMngAdd`| The command to run when adding a package. It can be a command or a script. |
101
+
|`iPkgMngRm`| The command to run when removing a package. It can be a command or a script. |
102
+
|`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. |
103
+
|`differURL`| The URL of the [Differ API](https://github.com/Vanilla-OS/Differ) service to use when comparing two OCI images. |
104
+
|`partLabelVar`| The label of the partition dedicated to the system's `/var` directory. |
105
+
|`partLabelA`| The label of the partition dedicated to the system's `A` root. |
106
+
|`partLabelB`| The label of the partition dedicated to the system's `B` root. |
107
+
|`partLabelBoot`| The label of the partition dedicated to the master boot. |
108
+
|`partLabelEfi`| The label of the partition dedicated to the EFI boot. |
109
+
|`thinProvisioning`| If set to `true`, ABRoot will use thin provisioning when creating the transaction volume. Check the section about [thin provisioning](#thin-provisioning) for more information. |
110
+
|`thinInitVolume`| The command to run to initialize the transaction volume. This is mandatory if `thinProvisioning` is set to `true`. |
111
+
|`libPathStates`| NOT_IMPLEMENTED |
112
+
113
+
## How it works
114
+
115
+
ABRoot works by performing transactions between two root partitions, `A` and `B`.
116
+
117
+
### Terminology
118
+
119
+
-**immutable** - a file or directory is immutable if it cannot be modified or
120
+
deleted by the user directly.
121
+
-**transaction** - a transaction in this context is the process of updating
122
+
the system or applying changes to it.
123
+
-**atomic** - a transaction is atomic if it is either fully applied or not
124
+
applied at all. There is no in-between state. This means that if a transaction
125
+
fails, the system will be kept in the same state as before the transaction
126
+
started, preventing the system from being left in an inconsistent state.
127
+
128
+
### Boot process
129
+
The system manages those root partitions by assigning them the `current` or
130
+
`future` roles. The `current` partition is the one that is currently being used
131
+
by the system (runtime), while the `future` partition is the one that will be
132
+
used after a successful transaction, by performing a reboot, and switching the
133
+
roles of the partitions.
134
+
135
+
The boot process is composed of 2 entities:
136
+
137
+
-**master boot** - the master boot is the first stage of the boot process. It
138
+
is responsible for loading the correct root-specific boot (GRUB config) and
139
+
the kernel (which is also root-specific).
140
+
-**root-specific boot** - the root-specific boot is the second stage of the
141
+
boot process. It is responsible for loading the kernel modules and the kernel
142
+
parameters, and then booting the kernel.
143
+
144
+
The following schema shows how the boot process works:
145
+
146
+
```
147
+
+--------------------+ +--------------------+
148
+
| | | |
149
+
| Master Boot | -> | Root-specific Boot |
150
+
| | | |
151
+
+--------------------+ +--------------------+
152
+
|
153
+
v
154
+
+-------------------+ +---------------------+
155
+
| | | |
156
+
| System | <- | Root-specific |
157
+
| | | Kernel |
158
+
+-------------------+ | |
159
+
+---------------------+
160
+
```
161
+
162
+
### Transaction process
163
+
164
+
The transaction process is composed of multiple stages (11 at the time of
165
+
writing this). Each stage is responsible for performing a specific task, and
166
+
then passing the control to the next stage. Since ABRoot v2 is still in
167
+
development, the transaction process could still change, so if you're
168
+
interested in the details, please check the source code for `ABSystem`, in the
169
+
`core` package.
170
+
171
+
172
+
## Thin provisioning
173
+
174
+
ABRoot supports (and suggests) thin provisioning, which allows for a more
175
+
efficient use of disk space.
176
+
177
+
LVM thin provisioning allows users to create virtual filesystems larger than
178
+
the available physical storage. This is possible due to LVM thin pools
179
+
allocating blocks when they are written, rather than when a volume gets created.
180
+
Thin provisioning is commonly found in places like VPS clusters, where a
181
+
provider can allocate a very large storage pool (e.g. 500TB) without needing
182
+
to have that amount of physical storage. This way, they can provide customers
183
+
with adequate storage limits and only buy more storage when it's actually
184
+
needed.
185
+
186
+
The following schema shows how an ABRoot compatible disk layout would look like
0 commit comments