Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: change markdown admonitions to MyST for Explanation/multipath section #123

Merged
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 9 additions & 6 deletions explanation/intro-to/multipath.md
Original file line number Diff line number Diff line change
Expand Up @@ -62,8 +62,9 @@ When the `user_friendly_names` configuration option is set to 'yes', the name of

You can also set the name of a multipath device to a name of your choosing by using the `alias` option in the `multipaths` section of the multipath configuration file.

> **See also**:
> For information on the multipath configuration defaults, including the `user_friendly_names` and `alias` configuration options, see {ref}`DM-Multipath configuration <configuring-multipath>`.
```{seealso}
For information on the multipath configuration defaults, including the `user_friendly_names` and `alias` configuration options, see {ref}`DM-Multipath configuration <configuring-multipath>`.
```

### Consistent multipath device names in a cluster

Expand Down Expand Up @@ -110,8 +111,9 @@ pvcreate /dev/mapper/mpatha

You can use the resulting LVM physical device when you create an LVM volume group just as you would use any other LVM physical device.

> **Note**:
> If you try to create an LVM physical volume on a whole device on which you have configured partitions, the `pvcreate` command will fail.
```{note}
If you try to create an LVM physical volume on a whole device on which you have configured partitions, the `pvcreate` command will fail.
```

When you create an LVM logical volume that uses active/passive multipath arrays as the underlying physical devices, you should include filters in the `lvm.conf` file to exclude the disks that underlie the multipath devices. This is because if the array automatically changes the active path to the passive path when it receives I/O, multipath will failover and fallback whenever LVM scans the passive path if these devices are not filtered.

Expand All @@ -127,5 +129,6 @@ After updating `/etc/lvm.conf`, it's necessary to update the `initrd` so that th
update-initramfs -u -k all
```

> **Note**:
> Every time either `/etc/lvm.conf` or `/etc/multipath.conf` is updated, the `initrd` should be rebuilt to reflect these changes. This is imperative when **denylists** and filters are necessary to maintain a stable storage configuration.
```{note}
Every time either `/etc/lvm.conf` or `/etc/multipath.conf` is updated, the `initrd` should be rebuilt to reflect these changes. This is imperative when **denylists** and filters are necessary to maintain a stable storage configuration.
```
14 changes: 8 additions & 6 deletions explanation/multipath/common-multipath-tasks-and-procedures.md
Original file line number Diff line number Diff line change
Expand Up @@ -90,10 +90,11 @@ Make sure to run `resize2fs /dev/mapper/mpathb` to resize the filesystem.

This is greatly simplified by the use of UUIDs to identify devices with an intrinsic label. To do this, install `multipath-tools-boot` and reboot your system. This will rebuild the initial RAM disk and afford multipath the opportunity to build its paths before the root filesystem is mounted by UUID.

> **Note**:
> Whenever `multipath.conf` is updated, initrd should be updated as well by running:
> `update-initramfs -u -k all`
> The reason for this is that `multipath.conf` is copied to the RAM disk, and is integral to determining the available devices to map via its `denylist` and `devices` sections.
```{note}
Whenever `multipath.conf` is updated, initrd should be updated as well by running:
`update-initramfs -u -k all`
The reason for this is that `multipath.conf` is copied to the RAM disk, and is integral to determining the available devices to map via its `denylist` and `devices` sections.
```

## The multipathd daemon

Expand Down Expand Up @@ -149,8 +150,9 @@ When displaying the multipath configuration, there are three verbosity levels yo
- **`-v1`** : Outputs only the created or updated multipath names, which you can then feed to other tools such as `kpartx`
- **`-v2`** : Prints all detected paths, multipaths, and device maps

> **Note**:
> The default verbosity level of multipath is 2 and can be globally modified by defining the verbosity attribute in the `defaults` section of `multipath.conf`
```{note}
The default verbosity level of multipath is 2 and can be globally modified by defining the verbosity attribute in the `defaults` section of `multipath.conf`
```

The following example shows the output of a `sudo multipath -l` command:

Expand Down
10 changes: 6 additions & 4 deletions explanation/multipath/configuring-multipath.md
Original file line number Diff line number Diff line change
Expand Up @@ -116,8 +116,9 @@ All the multipath attributes that can be set in the `defaults` section of the `m
* `ghost_delay`
* `enable_foreign`

> **Note**:
> Previously, the `multipath-tools` project provided a complete configuration file with all the most commonly used options for each of the most-used storage devices. Currently, you can see all those default options by running `sudo multipath -t`. This will dump a used configuration file including all the embedded default options.
```{note}
Previously, the `multipath-tools` project provided a complete configuration file with all the most commonly used options for each of the most-used storage devices. Currently, you can see all those default options by running `sudo multipath -t`. This will dump a used configuration file including all the embedded default options.
```

## Configuration file blacklist and exceptions

Expand Down Expand Up @@ -172,8 +173,9 @@ blacklist_exceptions {
}
```

> **Note**:
> A common use is to blacklist "everything" using a catch-all regular expression, and create specific `blacklist_exceptions` entries for those devices that should be handled by `multipath-tools`.
```{note}
A common use is to blacklist "everything" using a catch-all regular expression, and create specific `blacklist_exceptions` entries for those devices that should be handled by `multipath-tools`.
```

## Configuration file multipath section

Expand Down
7 changes: 4 additions & 3 deletions explanation/multipath/multipath-configuration-examples.md
Original file line number Diff line number Diff line change
Expand Up @@ -363,9 +363,10 @@ defaults {

### Example of a multipaths section

> **Note**:
> You can obtain the WWIDs for your LUNs by running: `multipath -ll`
> after the service `multipath-tools.service` has been restarted.
```{note}
You can obtain the WWIDs for your LUNs by running: `multipath -ll`
after the service `multipath-tools.service` has been restarted.
```

```
multipaths {
Expand Down