Skip to content

Commit 246d6d4

Browse files
ZegliusZeglius
committed
docs: add documentation at surface level
Using Discourse urls as fallback for missing content for now docs: add missing image files
1 parent f6c7356 commit 246d6d4

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

42 files changed

+881
-15
lines changed

‎docs/src/Advanced/Auto-Mounting Secondary Drives.md

+257
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,257 @@
1+
<div class="warning">
2+
3+
# WARNING!
4+
5+
> **Attention**: You may lose data on the drive(s) or result in an unbootable system if configured improperly.
6+
7+
> **Note:** MicroSD cards automatically mount without any manual intervention required on Bazzite.
8+
9+
> **Important**: Do **not** use the NTFS, exFAT, or FAT32 filesystems for game library storage.
10+
11+
Follow this guide **at your own discretion** and make sure to read the entire document relevant to your method, so you do not miss anything!
12+
13+
</div>
14+
15+
<hr>
16+
17+
# 1. Formatting a disk
18+
19+
> **Warning**: This will wipe all existing data on it
20+
21+
## Note when formatting in **KDE Partition Manager**
22+
23+
Make sure you set permissions to **everyone**.
24+
25+
Use a disk graphical user interface like KDE Plasma or GNOME Disks to format your drive. We recommend formatting secondary drives to **btrfs** or **ext4**.
26+
27+
### Creating a secondary drive directory and where to mount drives?
28+
29+
> **Note**: Drive directories should be **lowercase** with **no spaces** for best practice.
30+
31+
> **Attention**: `/var/mnt` should NOT be the path, but create a new **directory** in either `/var/mnt` or `/var/run/media/`.
32+
33+
- `/var/mnt/...` for **permanent** drives
34+
- `/var/run/media/...` for **removable** drives
35+
36+
You can make a directory in `/var/mnt/` by opening a host terminal and **entering this command in a host terminal**:
37+
38+
```command
39+
cd /var/mnt
40+
```
41+
42+
```command
43+
sudo mkdir /var/mnt/games
44+
```
45+
46+
The drive will now be mounted in a directory known as `games`.
47+
48+
> **Note**: `games` can be named anything you desire that fits best practices.
49+
50+
#### Permissions for the drive
51+
52+
```command
53+
sudo chown $USER:$USER /var/mnt/games
54+
```
55+
56+
> **Note**: If you plan to reformat the partition, remember to edit the mount point and "Remove" the mount path before you reformat! If not you will have to manually edit `/etc/fstab`.
57+
58+
# 2. Graphical User Interface (GUI) Methods for Auto-Mounting
59+
60+
> **Warning**: Do not set up auto-mount, unmount then format a drive! It can confuse the software you are configuring drives with. Instead, **remove the auto-mount first before formatting the drive**.
61+
62+
## KDE Partition Manager
63+
64+
![KDE|48x48](../img/kde_partition_manager_icon.png)
65+
66+
**This is pre-installed on KDE images.**
67+
68+
### Instructions
69+
70+
![KDE Partition Manager|690x462, 75%](../img/KDE_Partition_Manager.png)
71+
![Do not check the boxes!|690x197](../img/Do_not_check_the_boxes!.png)
72+
73+
1. Open KDE Partition Manager
74+
2. Locate the disk and partition you want to mount
75+
3. Right click on the partition and click "Edit Mount Point"
76+
4. Select "Identify by: UUID" (This will guarantee you mount THIS partition instead of a different one if the device nodes change for some reason)
77+
5. Select a mounting path:
78+
5a. You would want to use `/var/mnt/games` or something similar for permanent mounts
79+
6. **Untick all the boxes in the graphical application if they are checked**
80+
7. Click "More..." and add extra options depending on what filesystem is on the partition (read the "Filesystem Arguments" section)
81+
8. Click OK on both windows to save the mount points.
82+
9. Open the terminal to test the mounts by running the **command**:
83+
84+
```command
85+
sudo systemctl daemon-reload && sudo mount -a
86+
```
87+
88+
10. **If no errors appeared then it should be safe to reboot.**
89+
90+
> **Note**: If errors occur, then research the error and undo what you did and try again. Redo the previous two steps in the terminal (see CLI method down below and research how to use fstab) as KDE Partition Manager might not give a good error to search for if the test mount fails.
91+
92+
Display Name should be added too. Name it whatever you want it to be identified as.
93+
94+
#### Required additional options depending on **filesystem**
95+
96+
Use the below generic options depending on your filesystem (these are just good defaults)
97+
You can copy+paste these into the "More.." dialog and they will be valid
98+
99+
> **Note**: "Users can mount and unmount" is an **optional** setting.
100+
101+
#### Filesystem arguments
102+
103+
> **Warning**: If a drive is formatted, then do not remove it from `/etc/fstab`, so the "nofail" option is a must to avoid issues with booting.
104+
105+
![btrfs example|290x317](../img/btrfs_example.png)
106+
107+
> **Example: btrfs requires these additional options.**
108+
109+
##### **BTRFS**:
110+
111+
```command
112+
defaults,compress-force=zstd:3,noatime,lazytime,commit=120,space_cache=v2,nofail
113+
```
114+
115+
##### **Ext4**:
116+
117+
```command
118+
defaults,noatime,errors=remount-ro,nofail,rw,users,exec
119+
```
120+
121+
##### **NTFS**:
122+
123+
```command
124+
defaults,noatime,nofail,rw,users,exec
125+
```
126+
127+
> **Note**: Do not use the NTFS filesystem for game library storage in Bazzite, and it is not supported and you will get lots of issues with it. NTFS is **not** intended as a game drive for Bazzite.
128+
129+
#### Advanced Options (Not required for most setups)
130+
131+
##### Information about compression:
132+
133+
**3** is a good balance, older CPUs should use **1**.
134+
135+
##### Information about subvolumes:
136+
137+
use `subvol=name` as an option, KDE and GNOME Disks let you only mount 1 subvolume through the GUI, you can mount the root with `subvol=/` if a default subvolume is configured in the filesystem.
138+
139+
### Installing KDE Partition Manager on non-KDE images
140+
141+
If you would like to install this, then it can be layered to your system by entering in a terminal:
142+
143+
```
144+
rpm-ostree install kde-partitionmanager
145+
```
146+
147+
Reboot your system after it has finished installing the terminal.
148+
149+
## GNOME Disks
150+
151+
![GNOME|120x120, 50%](../img/GNOME_Disks_icon.png)
152+
153+
**This comes pre-installed on GNOME images.**
154+
155+
### Instructions
156+
157+
![GNOME_Disks|690x463, 75%](../img/GNOME_Disks.png)
158+
159+
1. Open GNOME Disks (`gnome-disk-utility`)
160+
2. Locate the disk and partition you want to mount
161+
3. Click the cog icon on the partition
162+
4. Select "Edit Mount Options"
163+
5. Turn off "User Session Default"
164+
6. Check:
165+
a) Mount at system startup
166+
b) Show in user interface
167+
7. In the space where this is no label: `nosuid,nodev,nofail,x-gvfs-show,` (refer to the correct filesystem below for more options)
168+
8. `/var/mnt/games` (or whatever directory you made)
169+
9. `auto`
170+
10. Select "Take Ownership"
171+
11. Open the terminal to test the mounts by running the **command**:
172+
173+
```command
174+
sudo systemctl daemon-reload && sudo mount -a
175+
```
176+
177+
12. **If no errors appeared then it should be safe to reboot.**
178+
179+
> **Note**: If errors occur, then research the error and undo what you did and try again. Redo the previous two steps in the terminal as GNOME Disks might not give a good error to search for if the test mount fails.
180+
181+
Display Name should be added too. Name it whatever you want it to be identified as.
182+
183+
#### Filesystem Arguments
184+
185+
> **Warning**: If a drive is formatted, then do not remove it from `/etc/fstab`, so the "nofail" option is a must to avoid issues with booting.
186+
187+
![GNOME_Edit_Mount_Options|690x465, 75%](../img/GNOME_Edit_Mount_Options.png)
188+
189+
![GNOME_Mount_Options|549x500, 75%](../img/GNOME_Mount_Options.png)
190+
191+
##### **BTRFS**:
192+
193+
```command
194+
defaults,compress-force=zstd:3,noatime,lazytime,commit=120,space_cache=v2,nofail
195+
```
196+
197+
##### **Ext4**:
198+
199+
```command
200+
defaults,noatime,errors=remount-ro,nofail,rw,users,exec
201+
```
202+
203+
##### **NTFS**:
204+
205+
```command
206+
defaults,noatime,nofail,rw,users,exec
207+
```
208+
209+
> **Note**: Do not use the NTFS filesystem for game library storage in Bazzite, and it is not supported and you will get lots of issues with it. NTFS is **not** intended as a game drive for Bazzite.
210+
211+
#### Permissions for the drive
212+
213+
```command
214+
sudo chown $USER:$USER /mnt/games
215+
```
216+
217+
#### Advanced Options (Not required for most setups)
218+
219+
##### Information about compression:
220+
221+
**3** is a good balance, older CPUs should use **1**.
222+
223+
##### Information about subvolumes:
224+
225+
use `subvol=name` as an option, KDE and GNOME Disks let you only mount 1 subvolume through the GUI, you can mount the root with `subvol=/` if a default subvolume is configured in the filesystem
226+
227+
### Installing GNOME Disks on non-GNOME images
228+
229+
If you would like to install this, then it can be layered to your system by entering in a terminal:
230+
231+
```
232+
rpm-ostree install gnome-disk-utility
233+
```
234+
235+
Reboot your system after it has finished installing the terminal.
236+
237+
# Alternative Methods (CLI)
238+
239+
There are also two command-line interface (CLI) methods.
240+
241+
1. Using `systemd.mount`
242+
243+
2. Editing the `/etc/fstab` file
244+
245+
CLI methods are intended for advanced users, and it is recommended to research one of the two methods elsewhere.
246+
247+
<hr>
248+
249+
# Emergency Mode After Following This Guide?
250+
251+
This video tutorial shows how to recover from your mounting mistakes.
252+
253+
<https://www.youtube.com/watch?v=-2wca_0CpXY>
254+
255+
<hr>
256+
257+
**Documentation Contributors**: [HikariKnight](https://github.com/HikariKnight) and [asen23](https://github.com/asen23)

‎docs/src/Advanced/GRUB Theming.md

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
See <https://universal-blue.discourse.group/docs?topic=370>

‎docs/src/Advanced/Modifying initramfs args and dracut.md

+69
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
HikariKnight | 2024-07-26 22:24:33 UTC | #1
2+
3+
# Before doing this, if you just plan to add options to a module, you should consider using a karg instead!
4+
5+
Touching the initramfs system and modprobe will slow down your updates so all your updates will take several minutes longer. In most cases what you want to do in modprobe can be done with simple kernel arguments,
6+
7+
In this example lets change the below modprobe options into a karg (kernel argument)
8+
9+
```
10+
options hid_apple fnmode=2
11+
```
12+
13+
This would translate to the karg:
14+
15+
```
16+
hid_apple.fnmode=2
17+
```
18+
19+
To add this to grub we issue the command.
20+
21+
```
22+
rpm-ostree kargs --append-if-missing="hid_apple.fnmode=2"
23+
```
24+
25+
This lets you change the module option without editing the initramfs system and is a lot faster whenever you update the system as the kernel arguments are not regenerated on each update.
26+
27+
However if you **want** to or must use modprobe files instead at the sacrifice of slowing down your update speed a lot, then proceed with the reading.
28+
29+
---
30+
31+
### Adding modprobe files to initramfs (this will slow down updates)
32+
33+
Should you need to add files to initramfs (lets say a modprobe file) then you will need to add that as a `dracut.conf` file.
34+
35+
For this example we will use `/etc/modprobe.d/hid_apple.conf` as the modprobe file we want to add, this contains
36+
37+
```
38+
options hid_apple fnmode=2
39+
```
40+
41+
To get this to work, we need it included in initramfs so we will make a dracut config file for it `/etc/dracut.conf.d/hid_apple.conf`
42+
This file has the content
43+
44+
```
45+
install_items+=" /etc/modprobe.d/hid_apple.conf "
46+
```
47+
48+
Once both those files are made we can now issue a rebuild with
49+
`rpm-ostree initramfs --enable`
50+
and reboot
51+
52+
### Enabling kernel modules through dracut (this will slow down updates)
53+
54+
_NOTE: If you need to add a new driver to the system, then you will need to make a custom image, this is about enabling drivers/modules that are disabled by default_
55+
56+
Enabling kernel modules that exists on the system image, you will need to make a `dracut.conf` file in `/etc/dracut.conf.d/`.
57+
For this example we will use our `/etc/dracut.conf.d/vfio.conf` file generated by
58+
`ujust setup-virtualization vfio-on` on bazzite
59+
60+
```
61+
add_drivers+=" vfio vfio_iommu_type1 vfio-pci "
62+
```
63+
64+
Once we save that file, you can issue an initramfs rebuild with
65+
`rpm-ostree initramfs --enable`
66+
67+
**Do not rebuild using the dracut command directly when using an atomic system!**
68+
69+
---

‎docs/src/Advanced/Plymouth Theming to Show Details.md

+21
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
nicknamenamenick | 2024-07-14 15:50:27 UTC | #1
2+
3+
For those who want to see the init log show if services are functional when their PC starts up:
4+
5+
![OK|666x500](../img/OK.png)
6+
7+
```command
8+
sudo plymouth-set-default-theme details
9+
```
10+
11+
Alternatively, create `/etc/plymouth/plymouthd.conf` manually
12+
13+
```command
14+
sudo rpm-ostree initramfs --enable --reboot
15+
```
16+
17+
<hr>
18+
19+
**Documentation Contributors**: Krin
20+
21+
---

0 commit comments

Comments
 (0)