Merge pull request 'Fix typographical errors in miscellaneous sections' (!200) from brettweir/user-documentation:proofread-misc into main

Reviewed-on: server/user-documentation#200
Reviewed-by: Peter Boy <pboy@noreply.forge.fedoraproject.org>
This commit is contained in:
Peter Boy 2026-07-15 12:03:26 +00:00
commit 0b5b3b1de7
14 changed files with 47 additions and 47 deletions

View file

@ -8,7 +8,7 @@ Steps to do to contribute to the documentation:
Fork this repository, so you are not pushing updates directly into the main branch.
Start adding the actual ASCIIDoc content. While writing, make sure your new source files are included in the nav.adoc configuration file of the module you are using (./modules/ROOT/ ).
Start adding the actual AsciiDoc content. While writing, make sure your new source files are included in the nav.adoc configuration file of the module you are using (./modules/ROOT/ ).
Also make sure to use local preview often to check your markup.
Once you finish, commit your changes and push them to your fork.
@ -58,22 +58,22 @@ Someone will see your pull request and either merge it, or provide feedback if t
```
1. Metadata definition.
2. A script that does a local build. It shows a preview of the site in a web browser on localhost:8080 by running a local web server. Uses podman/docker.
3. Licence information for the documentation.
3. License information for the documentation.
4. Configuration for the local web server mentioned above.
5. A definition file for the build script.
6. A "root module of this documentation component". Please read below for an explanation.
7. Directory containing **attachments** to be used on any page.
8. Directory containing **Iiages** to be used on any page.
8. Directory containing **images** to be used on any page.
9. **Menu definition.** Also defines the hierarchy of all the pages.
10. **Pages with the actual content.** They are organised into subdirectories for specific area of information.
11. Snippets of adoc files reusable in various documentations, organised into subdirectories for specific area of information.
10. **Pages with the actual content.** They are organized into subdirectories for specific area of information.
11. Snippets of adoc files reusable in various documentations, organized into subdirectories for specific area of information.
## Components and Modules
Antora introduces two new terms:
* **Component** Simply put, a component is a part of the documentation website with its own menu. Components can also be versioned. In the Fedora Docs, we use separate components for user documentation, the Fedora Project, Fedora council, Mindshare, FESCO, but also for subprojects such as CommOps or Modulartity.
* **Module** A component can be broken down into multiple modules. Modules still share a single menu on the site, but their sources can be stored in different git repositories, even owned by different groups. The default module is called "ROOT" (that's what is in this example). If you don't want to use multiple modules, only use "ROOT". But to define more modules, simply duplicate the "ROOT" directory and name it anything you want. You can store modules in one or more git repositories.
* **Component** - Simply put, a component is a part of the documentation website with its own menu. Components can also be versioned. In the Fedora Docs, we use separate components for user documentation, the Fedora Project, Fedora council, Mindshare, FESCO, but also for subprojects such as CommOps or Modularity.
* **Module** - A component can be broken down into multiple modules. Modules still share a single menu on the site, but their sources can be stored in different git repositories, even owned by different groups. The default module is called "ROOT" (that's what is in this example). If you don't want to use multiple modules, only use "ROOT". But to define more modules, simply duplicate the "ROOT" directory and name it anything you want. You can store modules in one or more git repositories.
## Local preview
@ -93,7 +93,7 @@ The result will be available at http://localhost:8080
### Installing Podman on Fedora
Newer Fedora Workstations comes with Podman preinstalled by default — if you do not have it, you need to install it using the following command:
Newer Fedora Workstations come with Podman preinstalled by default - if you do not have it, you need to install it using the following command:
```
$ sudo dnf install podman
@ -134,7 +134,7 @@ And replaced it with a pointer to my fork:
...
```
I could also point to a local repository, using `HEAD` as a branch to preview the what's changed without the need of making a commit.
I could also point to a local repository, using `HEAD` as a branch to preview what's changed without the need of making a commit.
**Note:** I would need to move the repository under the `docs-fp-o` directory, because the builder won't see anything above.
So I would need to create a `repositories` directory in `docs-fp-o` and copy my repository into it.

View file

@ -113,7 +113,7 @@ Fedora 43 updates Postgresql from version 16 directly to version 18, skipping on
$ systemctl status postgresql
$ sudo tar -cvJf /var/lib/pgsql/backups/postgres16-bak.tzx /var/lib/pgsql/data/
----
2. Replace installed version 18 by version 17 und use it to update your database
2. Replace installed version 18 by version 17 and use it to update your database
+
[source]
----
@ -135,7 +135,7 @@ $ mv /var/lib/pgsql/data_old /var/lib/pgsql/data_old_16
$ sudo dnf install postgresql-server postgresql-upgrade --allowerasing
$ sudo -u postgres postgresql-upgrade /var/lib/pgsql/data
----
5. Start postgresql und check if everything works again
5. Start postgresql and check if everything is working again
+
[source]
----

View file

@ -8,8 +8,8 @@ Peter Boy; Jan Kuparinen
[qanda]
Can I see a built preview of this template to get a better idea about the result?::
Of course you can! Just look at the README of the repository — it should tell you everything.
Of course you can! Just look at the README of the repository. It should tell you everything.
Is writing documentation hard and dreadful?::
Absolutely not (OK, just joking). Writing documentation in asciidoc is very simple and straightforward. And in fact, writing documentation makes you very happy. Just try and see for yourself!
Absolutely not (OK, just joking). Writing documentation in AsciiDoc is very simple and straightforward. In fact, writing documentation makes you happy. Just try it yourself!
How do I manage SELinux issues?::
First of all: Dont deactivate but resolve issues - (Link to Server Sysadmin Cockpit page and Quick Docs)
First of all: Dont deactivate but resolve issues - (Link to Server Sysadmin Cockpit page and Quick Docs)

View file

@ -10,7 +10,7 @@ Fredrik Arneving; Peter Boy; Jan Kuparinen
Fedora has already supported the ARM architecture, and specifically ARM Single Board Computers (SBCs), for quite some time. Especially for these there is also a Fedora Server Edition installation medium available. But there are a number of pitfalls to be aware of.
Once started as an experimentation and education tool, the technology evolved into an affordable but sufficiently powerful tool for many tasks of everyday life. Even though these devices are very miniature and limited in power, they offer enough strength, to install a dedicated modern, solid Linux system. This is especially true for the newer alternatives to the well known Raspberry Pi.
Originally introduced as an experimental and educational tool, the technology has evolved into an affordable yet sufficiently powerful solution for many everyday tasks. Although these devices are miniature and limited in power, they provide enough capability to install a dedicated modern, solid Linux system. This is especially true for newer alternatives to the wellknown Raspberry Pi.
SBC Fedora Server Edition takes advantage of the power available on SBC today to install a dedicated modern, solid server system. In the end Fedora Server works on application level exactly as otherwise familiar.
@ -34,7 +34,7 @@ These are just a few criteria that certainly need to be expanded.
Almost all board makers are very enthusiastic about using the open source Linux system to make their hardware usable at all and attractive to a wider audience, saving them the development of their own operating system or the licensing costs for a commercial system. They focus on the development of device drivers for their hardware, instead. In fact, to even boot, many of them require device specific software.
Unfortunately, manufacturers are sometimes much less enthusiastic to make these drivers freely available under an open source license and to integrate them into the mainline kernel. Their models are working with Linux, but only in a proprietary tainted version, propriarily customized by the manufacturer.
Unfortunately, manufacturers are sometimes much less enthusiastic to make these drivers freely available under an open source license and to integrate them into the mainline kernel. Their models work with Linux, but only in a proprietary, tainted version provided by the manufacturer.
Fedora is dedicated and uncompromisingly Free Software, for good reason. All software involved must be open source and freely available. Fedora uncompromisingly insists on the reproducibility of all software components on their own hardware and under their complete control - especially for security and anti-fraud reasons.

View file

@ -9,7 +9,7 @@ Fredrik Arneving; Peter Boy; Emmanuel Seyman
:page-aliases: pages/installation/on-sbc.adoc
[abstract]
ARM Single Board Computers originally had only __one data storage medium__, an SD card. And they use to have no BIOS or equivalent firmware to initialize the hardware at boot time and make it accessible. The operating system has to provide this function, too. The u-boot bootloader is one of several options for providing this function. Therefore, the installation method for SBC devices works quite differently from what is otherwise known from Fedora.
ARM Single Board Computers typically have only __one data storage medium__, an SD card, with no BIOS or equivalent firmware to initialize the hardware at boot time and make it accessible. The operating system has to provide this function, too. The u-boot bootloader is one of several options for providing this function. Therefore, the installation method for SBC devices works quite differently compared to other platforms.
// Please, comment in the Warning below when you start
@ -41,7 +41,7 @@ Even though the installation works quite differently, Fedora Server ultimately f
+
[WARNING]
====
The critical passage is "supported by Fedora". When choosing a device for Fedora Server, check carefully if it is really actually supported. Unlike the x86 universe, don't expect everything to work just as smoothly in ARM rsp. aarch64. Take everything with a grain of salt. It is best to ask in advance on the arm mailing list or Matrix room.
The critical passage is "supported by Fedora". When choosing a device for Fedora Server, check carefully if it is really actually supported. Unlike the x86 universe, don't expect everything to work just as smoothly in ARM, e.g. aarch64. Take everything with a grain of salt. It is best to ask in advance on the arm mailing list or Matrix room.
====
* A *Fedora system*, which provides the Fedora utility program, __arm-image-installer__.
@ -65,7 +65,7 @@ For practical reasons, the downloaded deliverable is limited to just under 8 GB
Many SBC models today offer additionally alternative storage media, especially eMMC memory, either pluggable or soldered. Nevertheless, the installation procedure remains basically the same.
These SBCs can alternatively boot and operate directly from this remarkable faster memory. A pluggable memory can be connected to the desktop with an adapter. It is then the target for the image transfer, instead of the SD card. instead of the SD card. In case of soldered memory, you must first go through the installation process with the SD card, and then use that system to copy an installation image to the internal eMMC memory in a second step.
If using a pluggable memory, connect it to the desktop with an adapter; it becomes the target for the image transfer instead of the SD card. For soldered memory, first use the SD card for installation, then copy the image to the internal eMMC memory in a second step.
Some models provide a special flash module (SPI) to store a custom bootloader. For these cases, the u-boot bootloader offers a special format that is flashed onto the SPI module. This requires a board-specific tool independent from Fedora. The Fedora Server unified basic image file is transferred to the installation medium unchanged.
@ -97,7 +97,7 @@ Fedora-Server-Host-Generic-43-1.6.aarch64.raw.xz: OK
sha256sum: WARNING: 17 lines are improperly formatted
----
+
The result message includes a complain about some not correct formated lines. It can savely be ignored.
The result message includes a complaint about some incorrectly formatted lines. It can safely be ignored.
3. Connect your Micro SD card to your desktop. Identify the device name.
+
@ -105,17 +105,17 @@ The result message includes a complain about some not correct formated lines. It
----
$ lsblk
NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINT
sda 8:0 0 596,2G 0 disk
sda 8:0 0 596.2G 0 disk
├─sda1 8:1 0 600M 0 part /boot/efi
├─sda2 8:2 0 1G 0 part /boot
├─sda3 8:3 0 30G 0 part
│ └─sysvg-root 253:0 0 15G 0 lvm /
└─sda4 8:4 0 564,6G 0 part
└─sda4 8:4 0 564.6G 0 part
├─usrvg-var_log 253:1 0 5G 0 lvm /var/log
└─usrvg-libvirt 253:2 0 200G 0 lvm /var/lib/libvirt
mmcblk0 179:0 0 29,5G 0 disk
└─mmcblk0p1 179:1 0 29,5G 0 part
zram0 252:0 0 7,5G 0 disk [SWAP]
mmcblk0 179:0 0 29.5G 0 disk
└─mmcblk0p1 179:1 0 29.5G 0 part
zram0 252:0 0 7.5G 0 disk [SWAP]
----
4. In the above example the device is obviously _/dev/mmcblk0_ and its partition (mmcblk0p1) is not mounted anywhere. If it were, you would have to unmount the device.

View file

@ -127,13 +127,13 @@ At a convenient location, create a directory where you will store all your worki
$ mkdir ~/imagefactory
----
It will primarly used to store the kickstart and the template files. You may use your personal accout and use sudo for all commands. However, it is more convenient to work as root. However, this is only advisable in a dedicated VM as explained above.
It will primarily be used to store the kickstart and the template files. You may use your personal account and use sudo for all commands. However, it is more convenient to work as root. This is only advisable in a dedicated VM as explained above.
==== The kickstart file
The kickstart file describes the content of the disk image to create. Fetch the link:{attachmentsdir}/tutorials/imagefactory/fedora-server-kvm-dev.ks[basic kickstart file "fedora-server-kvm-dev.ks"]. Probably it is a good idea to clone the https://pagure.io/fedora-kickstarts[Fedora kickstart repository] as well. It may be advantageous to check for a file with a similiar target you want to create and start with that. In any case, a look at the various Kickstart files can give you ideas on how to achieve your goal.
1. Fetch the link:{attachmentsdir}/tutorials/imagefactory/fedora-server-kvm-dev.ks[basic kickstart file] and store it into this working directory. In many cases klicking the link stores the file into you default download directory, ~/Downloads in case of Fedora desktops or Macs.
1. Fetch the link:{attachmentsdir}/tutorials/imagefactory/fedora-server-kvm-dev.ks[basic kickstart file] and store it into this working directory. In many cases clicking the link stores the file into you default download directory, ~/Downloads in case of Fedora desktops or Macs.
+
[source,console]
----
@ -189,7 +189,7 @@ url --url="https://kojipkgs.fedoraproject.org/compose/branched/Fedora-38-2023031
==== The template file
The template file describes meta data of the disk image to create. That includes the repository to download and the size of the disk image. Don't worry too much about the download URL. It will be overwritten by the kickstart file.
Fetch the corresponding link:{attachmentsdir}/tutorials/imagefactory/fedora-server-kvm-dev.tdl[basic template file] and store it into the working directory. In many cases klicking the link stores the file into you default download directory, ~/Downloads in case of Fedora desktops or Macs.
Fetch the corresponding link:{attachmentsdir}/tutorials/imagefactory/fedora-server-kvm-dev.tdl[basic template file] and store it into the working directory. In many cases clicking the link stores the file into you default download directory, ~/Downloads in case of Fedora desktops or Macs.
[source,console]
----

View file

@ -30,9 +30,9 @@ Another good first overview provides the https://fedoramagazine.org/[_Fedora Mag
* We assume a correctly installed Fedora Server Edition release 38 or 39. For details see xref::installation/index.adoc[Fedora Server Installation Guide].
* Wordpress stores most of the content in a database. Accordingly, it requires access to a working database system and doesn't even startup without. Currently, it https://wordpress.org/plugins/postgresql-for-wordpress/[no longer enables to use PostgreSQL], the Fedora Server Edition preferred and specifically supported database system. It just supports MariaDB or MySQL, which are included in Fedora as well.
* Wordpress stores most of the content in a database. Accordingly, it requires access to a working database system and doesn't even start up without. Currently, it https://wordpress.org/plugins/postgresql-for-wordpress/[no longer supports PostgreSQL], the Fedora Server Edition preferred and specifically supported database system. It just supports MariaDB or MySQL, which are included in Fedora as well.
+
So you have to install either MariaDB or MySQL following xref::quickdocs/installing-mysql-mariadb.adoc[Installing MySQL/MariaDB]. In terms of Wordpress, both systems work equally smoothly. Following Fedoras preferrence for truely OSS software we use MariaDB here.
So you have to install either MariaDB or MySQL following xref::quickdocs/installing-mysql-mariadb.adoc[Installing MySQL/MariaDB]. In terms of Wordpress, both systems work equally smoothly. Following Fedora's preference for truly OSS software we use MariaDB here.
+
Before you start installation, create the xref::installation/index.adoc#_storage_organization[required storage]. The easiest and quickest way is to use Cockpit (select the storage tab and then the appropriate Volume Group in the upper right corner).
@ -47,7 +47,7 @@ If not already done install the xref:services/httpd-basic-setup.adoc[Fedora Web
+
[source,bash]
----
# dnf install wordpress
# dnf install wordpress
----
. Add a database and a database user for Wordpress to the MariaDB DB.
+
@ -74,7 +74,7 @@ Server version: 10.5.20-MariaDB MariaDB Server
Copyright (c) 2000, 2018, Oracle, MariaDB Corporation Ab and others.
Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.
Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.
MariaDB [wordpress]> quit
$
@ -95,7 +95,7 @@ define( 'DB_HOST', 'xxxx' );
. Enabling public access
+
For security reasons, the default configuration restricts access to the local system, which is usually not why you install Wordpress. You have to edit the cpnfiguration file.
For security reasons, the default configuration restricts access to the local system, which is usually not why you install Wordpress. You have to edit the configuration file.
+
[source,bash]
----
@ -163,7 +163,7 @@ Re-type new password:
== Check out and configure your site
. On your desktop open a Broser and navigate to the base address of the site you just configured:
. On your desktop open a Browser and navigate to the base address of the site you just configured:
+
[source,bash]
----

View file

@ -23,7 +23,7 @@ You will find
* LXQt-Desktop
* Cinnamon Desktop
* MATE Desktop
* Sugar Desktop Environment
* Sugar Desktop Environment
* Deepin Desktop
* i3 desktop
* Pantheon Desktop
@ -84,7 +84,7 @@ In a terminal window, you can directly switch to another desktop:
Without naming the new desktop, a window with the available options will be displayed.
The graphical `_Desktop Switcher_` is included in the Systemadministration menu group. It always displayx a list of available desktops you can choose from.
The graphical `_Desktop Switcher_` is included in the System Administration menu group. It always displays a list of available desktops you can choose from.
You can switch back to booting to a text console:

View file

@ -1,9 +1,9 @@
// Text excerpt about installing fail2ban
// consumer postinstallation-tasks.adoc (main), hetzner-dc.adoc
//
Open Cockpit in your desktops browser
Open Cockpit in your desktop's browser
`https://host.example.com:9090`. Accept the security warning of your browser. Cockpit uses a self signed certificate.
If you disabled root access during installation (recommended), login as root is not possible.
If you disabled root access during installation (recommended), logging in as root is not possible.
Login with your administrative user account. At the top you will see a warning that the Web Console is running with limited permissions. Enable administrator access so that all administrative privileges are automatically available after login.

View file

@ -1,6 +1,6 @@
// Text excerpt about installing fail2ban
// consumer postinstallation-tasks.adoc (main), hetzner-dc.adoc
There are several ways to improve the security of Cockpit axxess. All of them are based on permanently withdrawing access to Cockpit in the firewall. So, reconfigure the firewall permanently.
There are several ways to improve the security of Cockpit access. All of them are based on permanently withdrawing access to Cockpit in the firewall. So, reconfigure the firewall permanently.
[source,]
----
@ -37,6 +37,6 @@ c. Use a secure local proxy
+
* Install Cockpit on your local Fedora workstation or on a lab server shielded by a firewall. Configure this instance to access any of your remote Cockpit instances using Cockpits remote administration capability. It uses a protected ssh connection in the public network.
+
* In the upper left corner of Cockpit you will see the name of the logged in user and the desktop rsp. the (local) lab server name, along with an expand icon. This opens a box where you can switch to another server or add a new one.
* In the upper left corner of Cockpit you will see the name of the logged-in user and the (local) lab server name, along with an expand icon. This opens a box where you can switch to another server or add a new one.
+
* The `Add new host` link opens a simple form to fill in hostname and user. Use your administrative user name on the (remote) server. And you can assign a color. Select automatic login via ssh keyfile. Cockpit will create one for you if none exists or otherwise uses an existing one. For a newly created key, Cockpit installs the public key on the remote server, too.

View file

@ -1,9 +1,9 @@
// Text excerpt about setting up a comfortable, key-based user login
// consumer postinstallation-tasks.adoc (main), hetzner-dc.adoc
//
A key file for SSH saves the annoying and error-prone typing of the hopefully secure and sufficiently long password. Additionally, you may prepare your local desktop to use a short name instead of having to type in a complete FQN hostname.
An SSH key file saves the otherwise annoying and errorprone typing of the hopefully secure and sufficiently long password. Additionally, you may prepare your local desktop to use a short name instead of having to type in a complete FQN hostname.
a. On your desktop (Linux or macOS), create a SSH keyfile if not already available. It should not be secured by password to enable automatic processing.
a. On your desktop (Linux or macOS), create an SSH keyfile if not already available. It should not be secured by password to enable automatic processing.
+
[source,]
----

View file

@ -24,7 +24,7 @@ b. Reload the sshd daemon
c. Test that everything works as expected
+
* Is an authorised user able to log in?
* Is an authorized user able to log in?
* Are other users rejected with the message "Permission denied (publickey,gssapi-keyex,gssapi-with-mic)"?
* If this does not work and/or other users are able to log in with a password besides your known authorized user,
** install the latest updates.

View file

@ -1,6 +1,6 @@
// Text excerpt about installing fail2ban
// consumer postinstallation-tasks.adoc (main), hetzner-dc.adoc
The software monitors the log files for authentication errors. In case of multiple retries from the same IP address, it reconfigures the firewall on the fly to block the source IP. This is to prevent brute force methods for cracking passwords and bots checking for weak passwords. However, a system administrator may also lock himself out, if they happen to make a mistake. Therefore, you can exclude destinct IP addresses, e.g. the administrators desktop, from blocking.
The software monitors the log files for authentication errors. In case of multiple retries from the same IP address, it reconfigures the firewall on the fly to block the source IP. This is to prevent bruteforce methods for cracking passwords and bots checking for weak passwords. However, a system administrator may also lock himself out if a mistake is made. Therefore, you can exclude distinct IP addresses, e.g., the administrator's desktop, from blocking.
a. Installation of the software
+
@ -23,7 +23,7 @@ bantime = 6600
backend = auto
# The main configuration file defines all services but
# deactivates them by default. We have to activate those neeeded
# deactivates them by default. We have to activate those needed
[sshd]
enabled = true
----
@ -38,4 +38,4 @@ d. Control in the log
[source,]
----
[…]# tail -f /var/log/fail2ban.log
----
----

View file

@ -4,7 +4,7 @@
Fedora includes a tool, dnf-automatic, which supports several modes of update automation:
do not apply, notify admin, apply and notify admin, apply without notification. In particular, alternatives 2 and 3 are definitely worth considering. A general principle might be: Alternative 2 is the minimum choice for almost any system, alternative 3 is not at all suitable for critical systems that must not fail under any circumstances.
We recommend to install at least alternative 2:
We recommend installing at least alternative 2:
[source,]
----
[…]# dnf install dnf-automatic