diff --git a/docs/user/interactive.md b/docs/user/interactive/index.md similarity index 90% rename from docs/user/interactive.md rename to docs/user/interactive/index.md index 6948bf9..79b9cda 100644 --- a/docs/user/interactive.md +++ b/docs/user/interactive/index.md @@ -77,7 +77,7 @@ Agama makes it easy to adjust your network configuration. It allows setting up w devices, specifying the mode (DHCP/manual), IP addresses, name servers, etc. Advanced connections types, like bridges or bonds, does not have support in the user interface yet. However, it is a matter of time that they get added, given that Agama supports many of them during an -[unattended installation](./unattended.md) or using the [command-line interface](./cli.md). +[unattended installation](../unattended/index.md) or using the [command-line interface](../cli.md). :::warning Changes are applied instantly Beware that network configuration changes are applied instantly. So you must be careful when @@ -88,15 +88,13 @@ adjusting the network configuration on a remote installation. ### Storage -Without a doubt, storage configuration is one of the strongest areas of YaST. And, although it is -still a work in progress, Agama aims to play in the same league. Advanced features are landing into -Agama at good pace, especially because it shares most of the storage-related codebase with YaST. +Setting up the different file systems and their corresponding logical devices -like partitions, +LVM volumes or RAIDs- is one of the most complex aspects of the installation. Agama offers +great flexibility in that regard. -However, when it comes to the user interface, Agama approach is rather different. +The Agama approach to storage configuration is detailed on its own [separate section](./storage.md). - - -![Storage configuration, including devices selection, encryption, partitions and file systems, etc.](/img/storage.png) +![Overview of the storage configuration page](/img/storage.png) ### Software @@ -148,4 +146,4 @@ ssh root@agama.local ``` If you want to know more about the mDNS support, please check the [remote access -documentation](./remote.md). +documentation](../remote.md). diff --git a/docs/user/interactive/storage.md b/docs/user/interactive/storage.md new file mode 100644 index 0000000..20c883d --- /dev/null +++ b/docs/user/interactive/storage.md @@ -0,0 +1,146 @@ +# Configuration of storage devices + +This section describes some general aspects of the planned features for Agama regarding +storage setup and shows how the web interface can be used to configure the related +settings. + +:::warning Under development +Bear in mind that some of the mentioned features may be already available and fully working as +described while others may still be incomplete in the current version of Agama. + +In particular, the presented interface is still under heavy development and not available at the +latest version of Agama. As a result, the screenshots are not a faithfull representation of the +final look & feel. Something that is represented as a sentence in the screenshots can become a +tool-tip, a given icon can become a label, actions grouped in a drop-down can end up being +represented as separate buttons, etc. +::: + +## The general approach + +Agama uses the same algorithm and similar configurations for both interactive and unattended +installations, combining capabilities of the traditional YaST proposal (usually known as Guided +Setup) and the AutoYaST profile. Those configurations can be specified using the web interface +or through a JSON-based configuration profile. + +Agama can work with very detailed descriptions on how the storage setup must look like, analogous to +the specifications produced by YaST's Expert Partitioner or the AutoYaST profile which both include +every single detail about partitions, file systems or LVM structures. + +On the other hand, Agama can automatically determine any omitted aspect of the configuration, based +on the definition of the operating system to install ("product" in Agama jargon) and the properties +of the system, without the user specifying, or even understanding, every single configuration +option. + +That opens the door for configurations with any level of detail. For example, the user can use the +web interface to specify the creation of a root ("/") file system and a swap space, with no further +information. Agama would then infer all the details of the file systems (like the type, the mount +parameters, usage of Btrfs snapshots...) and would calculate appropriate sizes for the associated +partitions. The user can decide at any point to override any of the automatic values (eg. specifying +a size range for a partition) or to go back to the automatic mode for that particular setting. + +Something similar happens with complex structures like LVM or RAID, that can be specified in a quite +loosely way, as explained below. + +## Overall description of the Storage page + +Agama does not offer a direct replacement for the YaST Expert Partitioner. Although creating such a +tool is not discarded for the future, the Agama web interface should be enough to cover most of the +Expert Partitioner capabilities. In many cases, even in a more convenient way. + +The Storage section of the Agama web interface presents both the installer settings and the planned +result of applying those settings to the current system. + +![Overview of the storage configuration page](/img/user/storage-overview.png) + +The configuration defines which devices to use and how, which new logical devices to create (LVM, +software Raids, etc.) and where to allocate (or reuse) the file systems of the new operating system. +The result is currenty represented as a list of planned actions and a table representing the final +state of the affected devices. In the long term, a better alternative to show the result could be +developed. + +Every change to any of the configuration options will result in an immediate re-calculation of the +section that presents the result. As already mentioned, the configuration options are identical to +the case of unattended installation (see detailed description at the [corresponding +section](../unattended/storage.md)), although the user interface presents more clearly the +relationship between those settings and the system being used for installation. + +![Selecting a device for installation](/img/user/storage-device.png) + +There are several interactive elements allowing to control several aspects of the installation. + +![Choosing how to make space](/img/user/storage-space.png) + +By manipulating the configuration it is possible to extend the installation over several disks and +to reuse existing file systems, among many other things. + +![Using another disk for booting and reusing /home](/img/user/storage-two-disks.png) + +## Usage of LVM and software RAID + +Adding LVM and RAID is done using the same interface. + +![Adding LVM and RAID](/img/user/storage-add-device.png) + +Obviously, the file systems created on an LVM volume group will be created as logical volumes +analogous to the partitions of the disk case. Once again, it is possible to specify a loose +configuration simply indicating the disk (or disks) that will be used by LVM and Agama calculates +any partition that would be needed as physical volume, taking into account all the size overheads +and roundings introduced by the different technologies like LVM or the used partition table type. + +![A simple LVM setup](/img/user/storage-simple-lvm.png) + +The disks in which the LVM is set are also visible as part of the configuration, so it is possible +to tweak aspects like what to do with existing partitions or to define which disk will be used to +create the additional partitions needed for booting. + +It is also possible to be more concrete and specify some existing devices to be used as physical +volumes for any new LVM volume group. + +Defining a new RAID is done in a similar way from the same general user interface. Of course, LVM +and RAID can be combined making it possible to configure an LVM setup on top of a mirrored RAID +without explicitly creating any partition, delegating to Agama the creation of all the intermediate +data structures. + +## Configuration of partitions needed for booting + +One of the main features of the Agama storage setup is its ability to automatically determine any extra +partition that may be needed for booting the new system, like PReP, EFI, Zipl or any other described +at the [corresponding YaST +document](https://github.com/yast/yast-storage-ng/blob/master/doc/boot-requirements.md). The +algorithm can create those partitions or reuse existing ones that are already in the system if the +user wants to keep them. The behavior of that feature can be tweaked using the corresponding entry +at the advanced options menu. + +![Choosing how to make space](/img/user/storage-boot.png) + +## A note about transactional systems + +Agama is able to install transactional distributions like openSUSE MicroOS. There will be no option +at the Agama configuration to set whether the root file system of the installed system should be +transactional (also known as "immutable") or not. Since the implications go beyond the file system +settings, the nature of the system (transactional vs read-write) will be determined by the selection +of the product (ie. the operating system) to install. + +![Information about transactional system](/img/user/storage-transactional.png) + +## The initial proposal + +Defining the file systems is essential for installing the system, so Agama always makes an attempt +with an initial configuration before the user has had any opportunity to specify the settings (in +an interactive installation) or if the user has omitted the storage configuration (in an unattended +installation). + +The current logic to calculate those default settings is intentionally simplistic - just trying to +install into a single disk with the default product strategy to find space (eg. wiping the content +of the disk) and using the other default sizes and settings of the product (eg. Btrfs snapshots). + +That is an important difference with YaST, which tries really hard to find a configuration that +makes the installation possible even if that implies completely modifying the default settings (eg. +going for minimal sizes, disabling Btrfs snapshots and removing separate partitions) and making +attempts on every single disk (or combination of disks) in the system. + +The goal of the Agama approach is to provide a more consistent experience that makes the user part +of the decision making process and aware of the changes introduced at the configuration. Adding some +extra capabilities to that initial attempt (eg. trying on several disks or adjusting some very +visible parameters) is not fully discarded for the future, subject to finding the right way to make +those decisions obvious to the users. diff --git a/docs/user/unattended.md b/docs/user/unattended/index.md similarity index 93% rename from docs/user/unattended.md rename to docs/user/unattended/index.md index 7d5179b..2df52f8 100644 --- a/docs/user/unattended.md +++ b/docs/user/unattended/index.md @@ -55,6 +55,10 @@ Check the [JSON Schema](https://github.com/openSUSE/agama/blob/master/rust/agama-lib/share/profile.schema.json) to learn about the supported elements. +Some areas are relatively complex and just looking at the schema may not be enough to fully +understand how they work. That is definitely the case of the storage setup, that is described in its +own [separate section](./storage.md). + ### Dynamic profiles The profile can be adapted at runtime depending on the system where the auto-installation is @@ -105,4 +109,4 @@ sudo agama config show > profile.json To start an unattended installation process, you need to tell Agama where to find the profile. When using the Live ISO, you must use the `agama.auto` boot option. Please, check the [boot -options](boot_options.md) for further information. +options](../boot_options.md) for further information. diff --git a/docs/user/unattended/storage.md b/docs/user/unattended/storage.md new file mode 100644 index 0000000..750cf60 --- /dev/null +++ b/docs/user/unattended/storage.md @@ -0,0 +1,965 @@ +# Storage configuration + +The general concepts regarding configuration of storage devices with Agama are exposed at the +[corresponding subsection](../interactive/storage.md) of the interactive installation documentation. +It is recommended to read that section before diving into the details below. + +:::warning Under development +This document mentions some options that may still not be available in the current +implementation of Agama. +::: + +## Unattended installation using the legacy AutoYaST mode + +Most Agama profiles contain a `storage` section with the configuration settings that are detailed in +subsequent sections of this document. But in some cases, `storage` can be replaced by a special +section `legacyAutoyastStorage`, which is a 1:1 representation of the XML AutoYaST profile. This +section supports everything offered by the `partitioning` AutoYaST section. Note that Agama does not +validate this special section, so be careful to provide valid AutoYaST options. + +~~~json +{ + "legacyAutoyastStorage": [ + { + "use": "all", + "partitions": [] + } + ] +} +~~~ + +Although that special section is offered for backwards compatibility and to ease gradual migration +from AutoYaST to Agama, there are no plans to introduce any improvement or new feature in that +legacy mode. + +## Basic structure of the Storage section + +As mentioned above, the Agama process to setup the storage devices can be configured using a +`storage` section at the Agama configuration profile. The outer level of that section would look +like this, with all subsections being optional. + +``` +"storage": { + "drives": [ ... ], + "volumeGroups": [ ... ], + "mdRaids": [ ... ], + "btrfsRaids": [ ... ], + "nfsMounts": [ ... ] + "boot": { ... } +} +``` + +Thus, a `storage` section can contain several entries describing how to configure the corresponding +storage devices and some extra entries (currently only `boot`) to setup some general aspects that +influence the final layout. Check the Agama JSON schema for a more formal definition. + +Each volume group, RAID, bcache device or NFS share can represent a new logical device to be created +or an existing device from the system to be processed. Entries below `drives` represent devices +that can be used as regular disks. That includes removable and fixed disks, SD cards, DASD or zFCP +devices, iSCSI disks, multipath devices, etc. Those entries always correspond to devices that can be +found at the system, since Agama cannot create that kind of devices. + +In fact, a single entry can represent several devices from the system. That is explained in depth at +the section "searching existing devices" of this document. + +## Entries for describing the devices + +The specification of the previous section can be extended as we dive into the structure. + +For example, an element of the `drives` collection can contain the following fields. All of them are +optional and some of them are mutually exclusive. Check the schema and use Agama's built-in +validation process for more formal details. + +``` +{ + "alias": "...", + "search": { ... }, + "encryption": { ... }, + "filesystem": { ... }, + "partitions": [ ... ], + "ptableType": "..." +} +``` + +Normally the device represented by a `drive` entry will be divided into several partitions. Each +entry of `partitions` follows this structure with several optional fields. + +``` +{ + "alias": "...", + "search": { ... }, + "id": "...", + "size": { ... }, + "encryption": { ... }, + "filesystem": { ... }, + "delete": ..., + "deleteIfNeeded": ... +} +``` + +Drives and partitions can be combined to create a simple example in which the first disk is used to +create some partitions and the second one is directly formatted. + +```json +"storage": { + "drives": [ + { + "partitions": [ + { + "filesystem": { "path": "/" }, + "size": { "min": "10 GiB" } + }, + { + "filesystem": { "path": "swap" }, + "size": "2 GiB" + } + ] + }, + { + "filesystem": { "path": "/home" }, + } + ] +} +``` + +An entry from `volumeGroups` can have the following properties. + +``` +{ + "alias": "...", + "name": "...", + "search": { ... }, + "physicalVolumes": [ ... ], + "logicalVolumes": [ ... ], + "peSize": ... , + "delete": ... +} +``` + +Entries of `logicalVolumes` are relatively similar to the ones used to describe partitions. + +``` +{ + "alias": "...", + "search": { ... }, + "name": "...", + "size": { ... }, + "encryption": { ... }, + "filesystem": { ... }, + "pool": ..., + "usedPool": "...", + "stripes": ..., + "stripeSize": ..., + "delete": ..., + "deleteIfNeeded": ... +} +``` + +To illustrate how all the previously described elements fit together, let's see the following +example in which the first disk of the system is partitioned and a volume group is created on top of +that partition (after encrypting it) to allocate two file systems. + +```json +"storage": { + "drives": [ + { + "partitions": [ + { + "alias": "pv", + "id": "lvm", + "size": { "min": "12 GiB" }, + "encryption": { + "luks2": { "password": "my secret passphrase" } + } + } + ] + } + ], + "volumeGroups": [ + { + "name": "system", + "physicalVolumes": [ "pv" ], + "logicalVolumes": [ + { + "size": { "min": "10 GiB" }, + "filesystem": { "path": "/", "type": "btrfs" } + }, + { + "size": "2 GiB", + "filesystem": { "path": "swap", "type": "swap" } + } + ] + } + ] +} +``` + +Agama can also manage MD RAID arrays represented as entries at the `mdRaids` collection. + +``` +{ + "alias": "...", + "name": "...", + "search": { ... }, + "level": "...", + "chunkSize": ... , + "devices": [ ... ], + "size": { ... }, + "encryption": { ... }, + "filesystem": { ... }, + "partitions": [ ... ], + "ptableType": "...", + "delete": ... +} +``` + +In addition to traditional MD RAIDs, multi-device Btrfs file systems can also be defined as part of +the `btrfsRaids` section. + +``` +{ + "alias": "...", + "search": { ... }, + "dataRaidlevel": "...", + "metaDataRaidLevel": "..." , + "devices": [ ... ], + "label": "...", + "mkfsOptions": { ... }, + "subvolumePrefix": "...", + "subvolumes": [ ... ], + "snapshots": ..., + "quotas": ..., + "delete": ... +} +``` + +Last but not least, NFS shares can be mounted as entries at `nfsMounts`. + +``` +{ + "alias": "...", + "path": "...", + "mount": "..." +} +``` + +## Searching Existing Devices + +Many sections in the profile are used to describe how some devices must be created, modified or even +deleted. In the last two cases, it's important to match the description with one or more devices +from the system. + +If a description matches several devices, the same operations will be applied to +all. That's useful in several situations like applying the same partitioning schema to several disks +or deleting all partitions of a disk that match a given criteria. + +Matching is performed using a `search` subsection like described below, although not all the +capabilities are fully implemented and some aspects of the format may change during the +implementation phase. + +By default, all devices in the scope fitting the conditions will be matched. The number of device +matches can be limited using `max`. The following example shows how several `search` sections could +be used to find the three biggest disks in the system, delete all Linux partitions bigger than 1 GiB +within them and create new partitions of type RAID. + +```json +"storage": { + "drives": [ + { + "search": { + "sort": { "property": "sizeKib", "order": "desc" }, + "max": 3 + }, + "partitions": [ + { + "search": { + "condition": { + "and": [ + { "property": "id", "value": "linux" }, + { "property": "sizeGib", "value": 1, "operator": "greater" } + ] + } + }, + "delete": true + }, + { + "alias": "newRaidPart", + "id": "raid", + "size": { "min": "1 GiB" } + } + ] + } + ] +} +``` + +The example also serves to illustrate the scope of each search. That is, the devices from the system +that are considered as possible candidates. That obviously depends on the place in the profile of +the `search` section. A `search` section inside the description of an MD RAID will only match MD +devices and a `search` section inside the `partitions` subsection of that RAID description will only +match partitions of RAIDs that have matched the conditions of the most external `search`. + +A given device can never match two different sections of the Agama profile. When several sections +at the same level contain a search subsection, devices are matched in the order the sections appear +on the profile. + +```json +"storage": { + "drives": [ + { + "search": { + "sort": { "property": "sizeKib", "order": "desc" }, + "max": 1 + }, + "alias": "biggest" + }, + { + "search": { + "sort": { "property": "sizeKib", "order": "desc" }, + "max": 1 + }, + "alias": "secondBiggest" + } + ] +} +``` + +An empty search will match all devices in the scope, so the following example would delete all the +partitions of the chosen disk. + +```json +"storage": { + "drives": [ + { + "partitions": [ + { "search": {}, "delete": true } + ] + } + ] +} +``` + +If there is not a single system device matching the scope and the conditions of a given search, then +`ifNotFound` comes into play. If the value is "skip", the device definition is ignored. If it's +"error" the whole process is aborted. The value "create", which cannot be used for a drive, will +cause the `search` section to be ignored if no device matches. As a consequence, a new logical +device (partition, LVM, etc.) will be created. + +Entries on `drives` are different to all other subsections describing devices because drives can +only be matched to existing devices, they cannot be simply created. If `search` is omitted for a +drive, it will be considered to contain the following one. + +```json +{ + "search": { + "sort": { "property": "name" }, + "max": 1, + "ifNotFound": "error" + } +} +``` + +In some common cases, the syntax of a `search` subsection can be cumbersome. For that reason, it is +possible to use simple strings in some situations. + +On the one hand, `search` is very often used to find a device by its name. In that case, the search +section can simply contain the device name. + +```json +{ "search": "/dev/sda" } +``` + +On the other hand, the string "\*" allows to match all the devices from the current context, if +there is any. In other words, the two following search sections are equivalent. + +```json +{ "search": "*" } + +{ "search": { "ifNotFound": "skip" } } +``` + +## Referencing Other Devices + +Sometimes it is necessary to reference other devices as part of the specification of an LVM volume +group or RAID. Those can be existing system devices or devices that will be created as response to +another entry of the Agama profile. + +Aliases can be used for that purpose as shown in this example. + +```json +"storage": { + "drives": [ + { + "partitions": [ + { "size": "50 GiB", "id": "lvm", "alias": "newPV" } + ] + } + ], + "volumeGroups": [ + { + "name": "newVG", + "physicalVolumes": [ "newPV" ], + "logicalVolumes": [ { "name": "data", "size": "20 GiB" } ] + } + ] +} +``` + +If a section that matches several existing devices contains an alias, that alias will be considered +to be a reference to all the devices. As a consequence, this two examples are equivalent. + +```json +"storage": { + "drives": [ + { + "search": { + "sort": { "property": "sizeKib", "order": "desc" }, + "max": 1, + }, + "alias": "biggest" + }, + { + "search": { + "sort": { "property": "sizeKib", "order": "desc" }, + "max": 1, + }, + "alias": "secondBiggest" + } + ], + "mdRaids": [ + { + "devices": [ "biggest", "secondBiggest" ], + "level": "raid0" + } + ] +} + +"storage": { + "drives": [ + { + "search": { + "sort": { "property": "sizeKib", "order": "desc" }, + "max": 2, + "min": 2 + }, + "alias": "big" + } + ], + "mdRaids": [ + { + "devices": [ "big" ], + "level": "raid0" + } + ] +} +``` + +## Specifying the size of a device + +When creating some kinds of devices or resizing existing ones (if possible) it may be necessary to +specify the desired size. As seen in the specification above, that can be done in several ways. + +The most straightforward one is just using a string that can be parsed into a valid size. + +The second option is to provide a minimum size and an optional maximum one. The resulting size will +be between those thresholds. If the maximum is omitted the device will grow as much as possible, +taking into account the available spaces and all the other specified sizes. + +It is also possible to specify "current" as a minimum or maximum size limit for partitions and +logical volumes that already exist in the system (so "current" can only be used for device +specifications that contain a `search` section). The usage of "current" and how it affects +resizing the corresponding devices is explained at a separate section below. + +If the size is completely omitted for a device that already exists (ie. combined with `search`), +then Agama would act as if both min and max limits would have been set to "current" (which implies +the partition or logical volume will not be resized). + +Moreover, if the size is omitted for a device that will be created, Agama will determine the size +limits when possible. There are basically two kinds of situations in which that automatic size +calculation can be performed. + +On the one hand, the device may directly contain a `filesystem` entry specifying a mount point. +Agama will then use the settings of the product to set the size limits. In Agama Jargon, the +"product" is the operating system being installed. And each product specifies the default size +ranges for its relevant file systems like "/", "swap", "/home", etc. + +On the other hand, the size limits of some devices can be omitted if they can be inferred from other +related devices following some rules. + + - For an MD RAID defined on top of new partitions, it is possible to specify the size of all the + partitions that will become members of the RAID but is also possible to specify the desired size + for the resulting MD RAID and then the size limits of each partition will be automatically + inferred with a small margin of error of a few MiBs. + - Something similar happens with a partition that acts as the **only** physical volume of a new LVM + volume group. Specifying the sizes of the logical volumes could be enough, the size limits of the + underlying partition will match the necessary values to make the logical volumes fit. In this + case the calculated partition size is fully accurate. + - The two previous scenarios can be combined. For a new MD RAID that acts as the **only** physical + volume of a new LVM volume group, the sizes of the logical volumes can be used to precisely + determine what should be the size of the MD and, based on that, what should be the almost + exact size of the underlying new partitions defined to act as members of the RAID. + +The two described mechanisms to automatically determine size limits can be combined. Even creating +a configuration with no explicit sizes at all like the following example. + +```json +"storage": { + "drives": [ + { + "partitions": [ + { "alias": "pv" } + ] + } + ], + "volumeGroups": [ + { + "name": "system", + "physicalVolumes": [ "pv" ], + "logicalVolumes": [ + { "filesystem": { "path": "/" } }, + { "filesystem": { "path": "swap" } } + ] + } + ] +} +``` + +Assuming the product configuration specifies a root filesystem with a minimum size of 5 GiB and a +max of 20 GiB and sets that the swap must have a size equivalent to the RAM on the system, then +those values would be applied to the logical volumes and the partition with alias "pv" would be +sized accordingly, taking into account all the overheads and roundings introduced by the different +technologies like LVM or the used partition table type. + +## Partitions Needed for Booting + +Using a `boot` entry makes it possible to configure whether (and where, using an alias) Agama +should calculate and create the extra partitions needed for booting. If the device is not +specified, Agama will take the location of the root file system as a reference. + +```json +"storage": { + "drives": [ + { + "search": "/dev/sda", + "alias": "bootDisk" + }, + { + "search": "/dev/sdb", + "partitions": [ + { "filesystem": { "path": "/" } } + ] + } + ], + "boot": { + "configure": true, + "device": "bootDisk" + } +} +``` + +## Keeping an Existing File System or Encryption Layer + +The entries for both `encryption` and `filesystem` contain a flag `reuse` with a default value of +false. It can be used in combination with `search` to specify the device must not be re-encrypted +or re-formatted. + +## Deleting and Shrinking Existing Devices + +The storage proposal must make possible to define what to do with existing partitions and logical +volumes. Even with existing MD RAIDs or LVM volume groups. + +A `search` section allows to match the definition of a partition or an LVM logical volume with one +(or several) devices existing in the system. It is then possible to specify that the given +partitions or volumes must be: + + - Deleted if needed to make space for the newly defined devices + - Deleted in all cases + - Shrunk to the necessary size to make space for new devices + - Shrunk or extended to a given size, maybe a range + +It is even possible to express some combinations of the above, like "try to shrink it to make space +but proceed to delete it if shrinking it is not enough". + +Deletion can be achieved with the corresponding `delete` flag or the alternative `deleteIfNeeded`. +If any of those flags are active for a partition, it makes no sense to specify any other usage +(like declaring a file system on it). + +The following example deletes the partition with the label "root" in all cases and, if needed, keeps +deleting other partitions as needed to make space for the new partition of 30 GiB. + +```json +"storage": { + "drives": [ + { + "partitions": [ + { + "search": { + "condition": { "property": "fsLabel", "value": "root" } + }, + "delete": true + }, + { "search": {}, "deleteIfNeeded": true }, + { "size": "30 GiB" } + ] + } + ] +} +``` + +Often some partitions or logical volumes are shrunk only to make space for the declared devices. But +since resizing is not a destructive operation, it can also make sense to declare a given partition +must be resized (shrunk or extended) and then formatted and/or mounted. + +In any case, note that resizing a partition can be limited depending on its content, the filesystem +type, etc. + +Combining `search` and `resize` is enough to indicate Agama is expected to resize a given partition +if possible. The keyword "current" can be used as min and/or max for the size range and it is always +equivalent to the exact original size of the device. The simplest way to use "current" is to just +specify that the matched device should keep its original size. That's the default for searched (and +found) devices if `size` is completely omitted. + +```json +"storage": { + "drives": [ + { + "partitions": [ + { + "search": { + "condition": { "property": "fsLabel", "value": "reuse" } + }, + "size": { "min": "current", "max": "current" } + } + ] + } + ] +} +``` + +Other combinations can be used to specify how a device could be resized if possible. See the +following examples with explanatory filesystem labels. + +```json +"storage": { + "drives": [ + { + "partitions": [ + { + "search": { + "condition": { "property": "fsLabel", "value": "shrinkIfNeeded" } + }, + "size": { "min": 0, "max": "current" } + }, + { + "search": { + "condition": { "property": "fsLabel", "value": "resizeToFixedSize" } + }, + "size": "15 GiB" + }, + { + "search": { + "condition": { "property": "fsLabel", "value": "resizeByRange" } + }, + "size": { "min": "10 GiB", "max": "50 GiB" } + }, + { + "search": { + "condition": { "property": "fsLabel", "value": "growAsMuchAsPossible" } + }, + "size": { "min": "current" } + }, + ] + } + ] +} +``` + +Of course, when the size limits are specified as a combination of "current" and a fixed value, the +user must still make sure that the resulting min is not bigger than the resulting max. + +Both `deleteIfNeeded` and a size range can be combined to indicate that Agama should try to make +space first by shrinking the partitions and deleting them only if shrinking is not enough. + +```json +"storage": { + "drives": [ + { + "partitions": [ + { + "search": {}, + "size": { "min": 0, "max": "current" }, + "deleteIfNeeded": true + } + ] + } + ] +} +``` + +## Generating Partitions as MD RAID members + +MD arrays can be configured to explicitly use a set of devices by adding their aliases to the +`devices` property. + +```json +"storage": { + "drives": [ + { + "search": "/dev/sda", + "partitions": [ + { "alias": "sda-40", "size": "40 GiB" } + ] + }, + { + "search": "/dev/sdb", + "partitions": [ + { "alias": "sdb-40", "size": "40 GiB" } + ] + } + ], + "mdRaids": [ + { + "devices": [ "sda-40", "sdb-40" ], + "level": "raid0" + } + ] +} +``` + +The partitions acting as members can be automatically generated by simply indicating the target +disks that will hold the partitions. For that, the `devices` section must contain a `generate` +entry. + +```json +"storage": { + "drives": [ + { "search": "/dev/sda", "alias": "sda" }, + { "search": "/dev/sdb", "alias": "sdb" }, + ], + "mdRaids": [ + { + "devices": [ + { + "generate": { + "targetDisks": ["sda", "sdb" ], + "size": "40 GiB" + } + } + ] + "level": "raid0" + } + ] +} +``` + +As explained at the section about sizes, it's also possible to set the size for the new RAID letting +Agama calculate the corresponding sizes of the partitions used as members. That allows to use the +short syntax for `generate`. + +```json +"storage": { + "drives": [ + { "search": "/dev/sda", "alias": "sda" }, + { "search": "/dev/sdb", "alias": "sdb" }, + ], + "mdRaids": [ + { + "devices": [ { "generate": ["sda", "sdb" ] } ], + "level": "raid0", + "size": "40 GiB" + } + ] +} +``` + +## Generating Default Volumes + +Every product provides a configuration which defines the storage volumes (e.g., feasible file +systems for root, default partitions to create, etc). The default or mandatory product volumes can +be automatically generated by using a *generate* section in the *partitions* or *logicalVolumes* +sections. + +```json +"storage": { + "drives": [ + { + "partitions": [ + { "generate": "default" } + ] + } + ] +} + +``` + +The *generate* section allows creating the product volumes without explicitly writing all of them. +The config above would be equivalent to something like this: + +```json +"storage": { + "drives": [ + { + "partitions": [ + { "filesystem": { "path": "/" } }, + { "filesystem": { "path": "/home" } }, + { "filesystem": { "path": "swap" } } + ] + } + ] +} + +``` + +If any path is explicitly defined, then the *generate* section will not generate a volume for it. +For example, with the following config only root and swap would be automatically added: + +```json +"storage": { + "drives": [ + { + "partitions": [ + { "generate": "default" }, + { "filesystem": { "path": "/home" } } + ] + } + ] +} +``` + +The auto-generated volumes can be also configured. For example, for encrypting the partitions: + +```json +"storage": { + "drives": [ + { + "partitions": [ + { + "generate": { + "partitions": "default", + "encryption": { + "luks1": { "password": "12345" } + } + } + } + ] + } + ] +} +``` + +The *mandatory* keyword can be used for only generating the mandatory partitions or logical volumes: + +```json +"storage": { + "volumeGroups": [ + { + "name": "system", + "logicalVolumes": [ + { "generate": "mandatory" } + ] + } + ] +} +``` + +The *default* and *mandatory* keywords can also be used to generate a set of formatted MD arrays. +Assuming the default volumes are "/", "/home" and "swap", the following snippet would generate three +RAIDs of the appropriate sizes and the corresponding six partitions needed to support them. + +```json +"storage": { + "drives": [ + { "search": "/dev/sda", "alias": "sda" }, + { "search": "/dev/sdb", "alias": "sdb" }, + ], + "mdRaids": [ + { + "generate": { + "mdRaids": "default", + "level": "raid0", + "devices": [ + { "generate": ["sda", "sdb"] } + ] + } + } + ] +} +``` + +## Generating Physical Volumes + +Volume groups can be configured to explicitly use a set of devices as physical volumes. The aliases +of the devices to use are added to the list of physical volumes: + +```json +"storage": { + "drives": [ + { + "search": "/dev/vda", + "partitions": [ + { "alias": "pv2", "size": "100 GiB" }, + { "alias": "pv1", "size": "20 GiB" } + ] + } + ], + "volumeGroups": [ + { + "name": "system", + "physicalVolumes": ["pv1", "pv2"] + } + ] +} +``` + +The physical volumes can be automatically generated too, by simply indicating the target devices in +which to create the partitions. For that, a *generate* section is added to the list of physical +volumes: + +```json +"storage": { + "drives": [ + { + "search": "/dev/vda", + "alias": "pvs-disk" + } + ], + "volumeGroups": [ + { + "name": "system", + "physicalVolumes": [ + { "generate": ["pvs-disk"] } + ] + } + ] +} +``` + +If the auto-generated physical volumes have to be encrypted, then the encryption config is added to +the *generate* section: + + +```json +"storage": { + "drives": [ + { + "search": "/dev/vda", + "alias": "pvs-disk" + } + ], + "volumeGroups": [ + { + "name": "system", + "physicalVolumes": [ + { + "generate": { + "targetDevices": ["pvs-disk"], + "encryption": { + "luks2": { "password": "12345" } + } + } + } + ] + } + ] +} +``` diff --git a/src/pages/faq.md b/src/pages/faq.md index 8cc65d2..e636981 100644 --- a/src/pages/faq.md +++ b/src/pages/faq.md @@ -51,8 +51,9 @@ in many convenient and flexible ways. ## Where is the Expert Partitioner? There is currently no direct replacement for the YaST Expert Partitioner. All the capabilities are -still there and can be used from the unattended installation, but we have still not decided how to -expose them in the interactive interface. +still there and can be used from the unattended installation. It is also planned to offer most +capabilities of the Expert Partitioner at the web interface, but with a different approach. Check +the [documentation about storage](docs/user/interactive/storage) for more details. ## What about unattended installation? diff --git a/static/img/storage.png b/static/img/storage.png index 54446b9..6e576fd 100644 Binary files a/static/img/storage.png and b/static/img/storage.png differ diff --git a/static/img/user/storage-add-device.png b/static/img/user/storage-add-device.png new file mode 100644 index 0000000..c1b0225 Binary files /dev/null and b/static/img/user/storage-add-device.png differ diff --git a/static/img/user/storage-boot.png b/static/img/user/storage-boot.png new file mode 100644 index 0000000..549e184 Binary files /dev/null and b/static/img/user/storage-boot.png differ diff --git a/static/img/user/storage-device.png b/static/img/user/storage-device.png new file mode 100644 index 0000000..5e9caf7 Binary files /dev/null and b/static/img/user/storage-device.png differ diff --git a/static/img/user/storage-overview.png b/static/img/user/storage-overview.png new file mode 100644 index 0000000..433afc5 Binary files /dev/null and b/static/img/user/storage-overview.png differ diff --git a/static/img/user/storage-simple-lvm.png b/static/img/user/storage-simple-lvm.png new file mode 100644 index 0000000..e1d3231 Binary files /dev/null and b/static/img/user/storage-simple-lvm.png differ diff --git a/static/img/user/storage-space.png b/static/img/user/storage-space.png new file mode 100644 index 0000000..01e7c59 Binary files /dev/null and b/static/img/user/storage-space.png differ diff --git a/static/img/user/storage-transactional.png b/static/img/user/storage-transactional.png new file mode 100644 index 0000000..88b8c7a Binary files /dev/null and b/static/img/user/storage-transactional.png differ diff --git a/static/img/user/storage-two-disks.png b/static/img/user/storage-two-disks.png new file mode 100644 index 0000000..31d2177 Binary files /dev/null and b/static/img/user/storage-two-disks.png differ