From b4d141d8031ea395960a61eef3584ba57dae3d48 Mon Sep 17 00:00:00 2001
From: Peter Boy <pb@resdigita.de>
Date: May 24 2021 10:06:39 +0000
Subject: completed first version of SBC installation guide.


---

diff --git a/docs/modules/ROOT/assets/images/serverinstall-raspi-020.png b/docs/modules/ROOT/assets/images/serverinstall-raspi-020.png
deleted file mode 100644
index fc0e23e..0000000
Binary files a/docs/modules/ROOT/assets/images/serverinstall-raspi-020.png and /dev/null differ
diff --git a/docs/modules/ROOT/assets/images/serverinstall-raspi-030.png b/docs/modules/ROOT/assets/images/serverinstall-raspi-030.png
deleted file mode 100644
index 9f2013a..0000000
Binary files a/docs/modules/ROOT/assets/images/serverinstall-raspi-030.png and /dev/null differ
diff --git a/docs/modules/ROOT/assets/images/serverinstall-sbc-020.png b/docs/modules/ROOT/assets/images/serverinstall-sbc-020.png
new file mode 100644
index 0000000..83504ba
Binary files /dev/null and b/docs/modules/ROOT/assets/images/serverinstall-sbc-020.png differ
diff --git a/docs/modules/ROOT/assets/images/serverinstall-sbc-030.png b/docs/modules/ROOT/assets/images/serverinstall-sbc-030.png
new file mode 100644
index 0000000..fbfb600
Binary files /dev/null and b/docs/modules/ROOT/assets/images/serverinstall-sbc-030.png differ
diff --git a/docs/modules/ROOT/assets/images/serverinstall-sbc-060.png b/docs/modules/ROOT/assets/images/serverinstall-sbc-060.png
new file mode 100644
index 0000000..b73d7dd
Binary files /dev/null and b/docs/modules/ROOT/assets/images/serverinstall-sbc-060.png differ
diff --git a/docs/modules/ROOT/assets/images/serverinstall-sbc-090.png b/docs/modules/ROOT/assets/images/serverinstall-sbc-090.png
new file mode 100644
index 0000000..a3b7e58
Binary files /dev/null and b/docs/modules/ROOT/assets/images/serverinstall-sbc-090.png differ
diff --git a/docs/modules/ROOT/assets/images/serverinstall-sbc-100.png b/docs/modules/ROOT/assets/images/serverinstall-sbc-100.png
new file mode 100644
index 0000000..0a82f10
Binary files /dev/null and b/docs/modules/ROOT/assets/images/serverinstall-sbc-100.png differ
diff --git a/docs/modules/ROOT/pages/server-installation-sbc.adoc b/docs/modules/ROOT/pages/server-installation-sbc.adoc
index aa5f0da..b439f23 100644
--- a/docs/modules/ROOT/pages/server-installation-sbc.adoc
+++ b/docs/modules/ROOT/pages/server-installation-sbc.adoc
@@ -1,21 +1,23 @@
-= Fedora Server on Single Board Computers - Raspberry Pi & Co.
+= Installing Fedora Server on Single Board Computers - Raspberry Pi & Co.
 Peter Boy; Jan Kuparinen
 :page-authors: {author}, {author_2}
 
 [NOTE]
 ====
-__**– Work in Progress –**__ Please comment on server mailing list!
+__**– Beta 1 –**__ Please comment on server mailing list!
 ==== 
 [sidebar]
 ****
-Author: Peter Boy (pboy) | Creation Date: N/A | Last update: N/A | Related Fedora Version(s): 34
+Author: Peter Boy (pboy) | Creation Date: 2021-05-25 | Last update: 2021-05-25 | Related Fedora Version(s): 34
 ****
 
-Fedora Server is also available for Single Board Computers (SBC) like the legendary Raspberry Pi. That device started some years ago primarily as an experimentation and education tool. Fedora Server on such a DIY device?
+Fedora Server is also available for Single Board Computers (SBC) like the legendary Raspberry Pi. That device started some years ago primarily as an experimentation and education tool. 
 
-The technology evolved over the years into an affordable but sufficiently powerful tool for many task of everyday life. It ignited a new business field for many hardware producers, all of which, while keeping the basic concept, take the Raspberry Pi as a reference to surpass. This resulted in a rich variety of variants that is difficult to keep track of. They follow the same basic principle, but _differ in many, sometimes significant details_ regarding software support, installation and maintenance. 
+Fedora Server Edition on such a DIY device?
 
-While the installation procedure is completely different, in the end Fedora Server works exactly as otherwise familiar. 
+The technology evolved over the years into an affordable but sufficiently powerful tool for many task of everyday life. It ignited a new business field for many hardware makers, all of which, while keeping the basic concept, take the Raspberry Pi as a reference to surpass. This resulted in a rich variety of variants that is difficult to keep track of. They follow the same basic principle, but _differ in many, sometimes significant details_ regarding software support, installation and maintenance. 
+
+While the installation procedure is completely different from the standard Anaconda installation, in the end Fedora Server works on application level exactly as otherwise familiar. 
 
 [WARNING]
 ====
@@ -26,7 +28,7 @@ When choosing a device for Fedora Server, check carefully if it is actually supp
 
 Certainly, most prominent and well-known features are favorable price, low power consumption, and small footprint. 
 
-But it's not just pure affordability in several respects. The devices now offer a performance that is suitable for many typical tasks in the Soho area. Examples include mail, web, file servers, e-book or document library, media servers and more. And not only in the domestic sector, but also for smaller office environments. They can thus replace the popular NAS devices while offering significantly more performance and greater adaptability and flexibility - lower cost more as a side effect.
+But it's not just pure affordability in several respects. The devices now offer a performance that is suitable for many typical tasks in the Soho area. Examples include mail, web, file servers, e-book or document library, media servers and more. And not only in the domestic sector, but also for smaller office environments. They can thus replace the popular NAS devices while offering significantly more performance and greater adaptability and flexibility - reduced costs rather as a side effect.
 
 However, those properties also open up additional opportunities. 
 
@@ -37,21 +39,26 @@ Critical services such as monitor software can be offloaded to a dedicated devic
 A closer look opens up a multitude of possibilities.
 
 == How it works
-[source,txt]
-====
-Outline:
 
-* No installation procedure as described in the generic installation guide
-* A pre-installed server disk image is transferred to the SBC boot device, typically an SD or an eMMC card. 
-* The process is easy. During the transfer, the image is adapted to the specific hardware and an initial user-specific configuration is injected.
-====
+Single board computers originally had only one data storage medium, an SD card. And they were designed to boot directly from that SD card. There was no opportunity to boot from one medium and install to another. That original principle is still basically maintained today. The device expects a ready-to-use operating system, configured precisely for the respective hardware. The default boot medium is still an SD card, although many devices now offer eMMC, sometimes USB or even a SATA or NMVe hard disk as an alternative.
+
+Fedora distributes a generic Fedora Server Edition image, preconfigured for Raspberry Pi. Additionally, it provides a utility to transfer the image to the prospective boot medium, usually an SD card. Furthermore, the transfer program can reconfigure the image for an alternative SBC. Optionally, it can also make some adjustments to the initial configuration.
+
+== Special considerations: Organization of the storage area
+
+Fedora Server Edition creates by default a small /boot partition, used by grub2 bootloader and data needed during the initial boot phase, and in case of an uefi system an efi partition. It fills the remaining area with another partition and one volume group (VG) created therein. In that Volume Group, a logical volume of approx. 15 GB (the exact value depends on the disk capacity) is created for the operating system and its software. The other available space remains free for the creation of logical volumes (LVs) for user data, which are to be mounted at the appropriate positions in the directory tree of the system area.
+
+The rationale behind this is a separation of system and user data. This should ease system administration, increase security, and decrease error-proneness. The system area, i.e. the operating system including installed utility programs and software must be maintainable completely independently of the storage of user data. System maintenance must not jeopardise user data under any circumstances. If necessary, it must be possible to unmount user data.
 
+In the world of SBCs, all available space is usually allocated to a single (root) file system. Initially, the available storage media were also comparatively small. Any further segmentation would be impractical. Accordingly, the Fedora file system image does not provide for any segmentation. The transfer program that installs this image on a disk provides an option to fit the image to the available space, also without a differentiation option. 
 
-== Installing Fedora Server Edition on Raspberry Pi
+For sure, disk organization is an issue where hardly 2 system administrations agree on. As a rule of thumb, segmentation is not appropriate for a disk of 16gb or less. At a size of 32gb, it would be worth considering if it is a serious use with data of some relevance. For even larger volumes and serious use, it is definitely something to consider. 
+
+== Steps to install Fedora Server Edition on Raspberry Pi or an alternative
 
 === Prerequisites
 
-Of course, you need a Raspberry Pi, either model 3 or 4. And intended as a server it has to be connected to your network. For the first boot, a monitor and keyboard are required as well to perform an initial bare minimum configuration. Afterwards you will perform everything using either ssh or more confortably using Cockpit which is preinstalled and activated by default. 
+Of course, you need a Single Board Computer, either a Raspberry Pi model 2, 3, 4, or one of the supported alternatives. And intended as a server it has to be connected to your network. For the first boot, a monitor and keyboard are required as well, to perform an initial bare minimum configuration. Afterwards you will perform everything using either ssh or more comfortably using Cockpit, a graphical, web-based user interface, which is preinstalled and activated by default. 
 
 Additionally you need a Micro SD card to hold the operating system. Unless you intend to operate a database or e.g. a music library, a capacity of 32 gb should be fine and affordable nowadays. Avoid anything smaller than 16 gb.
 
@@ -59,7 +66,7 @@ And your desktop must be able to write to a SD card, either by a dedicated slot 
 
 === Preparations
 
-1. Set the download directory as default, fetch a Fedora Server Raspberry Pi system disk raw image, here F34, and check the integrity of the download.
+1. Set the download directory as default, fetch a Fedora Server aarch64 system disk raw image, here F34, and check the integrity of the download.
 +
 [source,bash]
 ----
@@ -75,7 +82,16 @@ And your desktop must be able to write to a SD card, either by a dedicated slot 
 On a Mac (Catalina) use shasum5.28 instead. 
 
 
-2. Connect youd Micro SD card to your desktop. Identify the device name and unmout the device. 
+2. On a Fedora Workstation, install arm-image-installer
++
+[source,bash]
+----
+[…]# dnf install  arm-image-installer uboot-images-armv8.noarch uboot-images-armv7.noarch
+----
++
+On a Mac or Windows Desktop you have to install VirtualBox or any other virtualization software and install Fedora as a guest system, and then thereon likewise arm-installer. If your device is a Raspberry Pi model 3 or 4 you don't need to make any adjustments and can install Balena Etcher instead to transfer the image to the SD card.
+
+3. Connect your Micro SD card to your desktop. Identify the device name and unmout the device if it is mounted. 
 +
 On a Fedora workstation you may use:
 +
@@ -117,14 +133,62 @@ On a Mac open a terminal und issue:
 […]# sudo  diskutil unmountDisk  /dev/disk2
 ----
 
-3. Transfer the raw disk image to the micro SD card
+4. Identify the name of the support files for your board
++
+[source,bash]
+----
+[…]# arm-image-installer --supported
+AllWinner Devices:
+A10-OLinuXino-Lime A10s-OLinuXino-M A13-OLinuXino A13-OLinuXinoM A20-OLinuXino-Lime A20-OLinuXino-Lime2 
+A20-OLinuXino-Lime2-eMMC A20-OLinuXino_MICRO A20-Olimex-SOM-EVB Ampe_A76 Auxtek-T003 Auxtek-T004 Bananapi 
+...
+TI Devices:
+am335x_evm am57xx_evm kc1 omap3_beagle omap5_uevm omap4_panda
+Note: For the am33xx BeagleBone devices use 'am335x_evm', BeagleBone AI use 'am57xx_evm'
+
+MVEBU Devices:
+clearfog helios4 
+
+ST Devices:
+stih410-b2260 
+
+Other Devices:
+arndale chiliboard cl-som-am57x rpi2 rpi3 rpi4 olpc_xo175
+----
++
+In the example above you find "rpi4" as the name of a Raspberry Pi Model 4.
++
+If you don't find your board, check the _boards.d_ directory directly just in case the list is not up to date.
++
+[source,bash]
+----
+[…]# ls -al /usr/share/arm-image-installer/boards.d  |  less
+----
++
+As an example., you will find the Radxa board "Rock Pi 4" model a and b as "rock-pi-4-rk3399"
+
+5. Transfer the raw disk image to the micro SD card
++
+[source,bash]
+----
+[…]# arm-image-installer --image=Fedora-Server-34-1.2.aarch64.raw.xz --target=rpi4 --media=/dev/mmcblk0 
+----
++
+Just in case you already decided to fill the complete space on disk with the root file system, you may add the --resizefs parameter which would result in an _alternative command line_:
 +
 [source,bash]
 ----
-[…]# xzcat Fedora-Server-34-1.2.aarch64.raw.xz | dd of=/dev/diskXXX bs=4M status=progress
+[…]# arm-image-installer --image=Fedora-Server-34-1.2.aarch64.raw.xz --target=rpi4 --resizefs --media=/dev/mmcblk0 
 ----
 +
-Alternatively, use a program like Balena Etcher. In this case, too, make sure that the SD card is not mounted. Otherwise, flashing the card will fail.
+In case of an alternative SBC as the Rock Pi 4 mentioned above would use __yet another command line__:
++
+[source,bash]
+----
+[…]# arm-image-installer --image=Fedora-Server-34-1.2.aarch64.raw.xz --target=rock-pi-4-rk3399 --media=/dev/mmcblk0 
+----
++
+Alternatively, in case of a Raspberry Pi model 3 or 4 use Balena Etcher, as explained above. In this case, too, make sure that the SD card is not mounted. Otherwise, flashing the card will fail.
 
 After the transfer is complete, unmount the SD card again if it was automatically re-mounted, and disconnect it.
 
@@ -138,6 +202,11 @@ Directly at a terminal of the Raspberry Pi we will make only the minimal, absolu
 3. Connect Raspberry Pi to power and wait. After some time you will be greeted by a very plain configuration screen.
 4. The only strictly necessary action is to configure root password. Type "4" and enter a suitable password. If you are on a non-US keyboard you should restrict yourself to traditional ASCII and avoid special characters for now. Otherwise, you might later not be able to enter the root password correctly, because a different keyboard mapping applies. In the next stage, with correct mapping, you can set up the password as complex as you like.
 5. Tap "c" to continue and finalize the configuration. After some waiting, the Fedora Server login prompt appears.
++
+[IMPORTANT]
+====
+Always complete this step and close with 'c'. Otherwise this installation routine can again and again conflict with the subsequent configuration.
+====
 6. Above the user input, a line with the (temporary) name of the computer and an IP address is displayed. The name is normally "fedora" and the IP address depends on the network. Note both carefully.
 7. You can now disconnect monitor and keyboard. The next steps all happen on the desktop.
 
@@ -145,11 +214,11 @@ Directly at a terminal of the Raspberry Pi we will make only the minimal, absolu
 
 1. On your desktop open a Browser and enter name and port __http://fedora:9090__. Sometimes the internal DNS already work. If not, use the IP address you wrote down, e.g. something like __http://192.168.158.116:9090__. After accepting a warning message due to a missing certificate, voilà, the Cockpit administration interface of the Raspberry Pi appears.
 +
-image::serverinstall-raspi-020.png[Cockpit Login Screen]
+image::serverinstall-sbc-020.png[Cockpit Login Screen]
 
 2. Login with your root account to continue configuration
 +
-image::serverinstall-raspi-030.png[Cockpit Overview Screen]
+image::serverinstall-sbc-030.png[Cockpit Overview Screen]
 
 3. First *adjust hostname*
 +
@@ -185,8 +254,153 @@ With everything done reboot the system. In the overview screen select either reb
   a. If your DHCP is correctly configured, you should be able to *find your device by name* now. Close your browser window and start again. Write the device name and port number in the address field, e.g. http://raspi3.exemple.com:9090 and Cockpit should come up again (after the usual warning about an insecure connection).
   b. You should be able to log in via **ssh as root and your key**. Try _ssh -i .ssh/MYKEY raspi3.example.com_ and after answering a question to accept the fingerprint you should gain access.
 
-== Organization of the storage area
+== Configuration of the storage area
+
+As explained at the beginning, there are at least three alternatives to organize the storage area.
+
+1. Filling all the space left after the base installation with the ROOT file system.
++
+This is the simplest solution and the only sensible one for disks of up to 16gb.
+
+2. Extend the partition and volume group to the remaining available disk space, extend the logical volume with the ROOT file system to about 12gb and leave the remaining area for logical volumes for dedicated payloads (database, libraries, etc.). 
++
+This is the most flexible solution and preserves all options for the system administrator depending on the actual progression of usage. It is especially recommended for disks of 64gb and more, but should also be considered with a size of 32 gb.
+
+=== Enlarge partition and volume group to fill the disk space 
+
+Alternate 1. and 2. as above start with the same administrative tasks.
+
+1. Login via ssh or switch to terminal in Cockpit (logged in as root)
+2. Use lsblk to determine the device name of your disk storage, most likely mmcblk1
+3. Invoke cfdisk with hat device name:
++
+[source,bash]
+----
+[…]# cfdisk /dev/mmcblk1
+----
+4. Select partition 3 (Type 8e Linux LVM) using <Cursor down> and then Resize using <Curser left>
++
+image::serverinstall-sbc-090.png[Partition resize]
+
+5. The suggested size fills the complete disk. Confirm with <Return>. Select "Write", confirm resizing and quit the program.
+6. Resize the volume group
++
+[source,bash]
+----
+[…]# pvresize  /dev/mmcblk1p3 
+ Physical volume "/dev/mmcblk1p3" changed
+ 1 physical volume(s) resized or updated / 0 physical volume(s) not resized
+----
+7. Select "Storage" in Cockpit and inspect the Volume Group _fedora_fedora_ in the upper right corner. The displayed size now shows an amount that indicates a complete fill of the entire disc.
+8. A click onto the fedora_fedora volume group brings up the logical volume view. In the "Logical volumes" list expand the root LV (/dev/fedora_fedora/root).
++
+image::serverinstall-sbc-100.png[Volume resize]
++
+For *alternative 1.* select "Grow" and expand the volume to fill the complete available space.
++
+For *alternative 2.* select "Grow" and expand the volume to sensible size. 10gb would be good to start with.
+
+9. Go back to the terminal. 
++
+[source,]
+----
+[…]# df -h 
+----
++
+Confirm that the size of the root file system is now of the specified value.
+
+After all the major modifications to the file system, it is now advisable to reboot before any further work is done.
+
+== Troubleshooting ==
+
+1. At the first system start the grub2 boot screen is displayed briefly, then the monitor remains dark. 
++
+Check if the network interface indicates a connection (the LEDs are on or blinking). In this case, it is likely that the device is fully booted and just the console interface is broken.
++
+Because in this case Cockpit is started and active on the device, use your Fedora desktop and search the network segment, e.g. 192.168.158.0/24 for devices with active port 9090. 
++
+[source,bash]
+----
+[…]# dnf install nmap
+[…]# nmap -Pn -p9090 192.168.158.0/24
+Starting Nmap 7.80 ( https://nmap.org ) at 2021-05-23 08:18 CEST
+Nmap scan report for fritz.box (192.168.158.1)
+Host is up (0.00052s latency).
+
+PORT     STATE  SERVICE
+9090/tcp closed nn-admin
+MAC Address: 34:81:C4:14:21:B4 (AVM GmbH)
+
+Nmap scan report for iMac.fritz.box (192.168.158.111)
+Host is up (0.00051s latency).
+
+PORT     STATE  SERVICE
+9090/tcp closed nn-admin
+MAC Address: 68:5B:35:97:9F:33 (Apple)
+...
+...
+Nmap scan report for raspi3.fritz.box (192.168.158.116)
+Host is up (0.00075s latency).
+
+PORT     STATE SERVICE
+9090/tcp open  nn-admin
+MAC Address: B8:27:EB:5A:EC:84 (Raspberry Pi Foundation)
+
+Nmap scan report for 192.168.158.120
+Host is up (0.00068s latency).
+
+PORT     STATE SERVICE
+9090/tcp open  nn-admin
+MAC Address: 06:BE:DE:31:C6:E2 (Unknown)
+...
+...
+Nmap done: 256 IP addresses (12 hosts up) scanned in 2.38 seconds
+----
++
+Look for an entry with open state of port 9090 and no hostname or unknown hostname. Among them you will probably find the device you are looking for. In the example above it is 192.168.158.120.
++
+Enter the address _https://192.168.158.120:9090_ into your browser. If successful, a cockpit login page opens, which simply outputs "fedora" as the hostname (in the lower part of the login widget). Otherwise, check the other suitable addresses.
++
+image::serverinstall-sbc-060.png[Cockpit Overview Screen]
++
+Unfortunately you can't log in right now because you don't know the password. 
++
+You have to rebuild the device operating system on SD card and add a SSH public key to be able to login via SSH and set a root password.  
++
+Beforehand you need to create pair of SSH keys if not already exist. It is best to create the key in the .ssh subdirectory of your home dir. It should not be secured by password to enable automatic processing. The naming with leading 'id_' und trailing types abbreviation, e.g. '_rsa' is just a common convention, yet helpful. Execute on the local desktop and adjust appropriately:
++
+[source,bash]
+----
+[…]# cd
+[…]# mkdir ~/.ssh
+[…]# ssh-keygen -t rsa -b 4096  -C "root@example.com" -f ~/.ssh/<outputkeyfile>
+----
++
+As an example you may use the name "__id_mysbc_rsa__". Although the type rsa is widely used, you may adjust your key type accordingly.
++
+Turn off the SBC, remove the SD card and connect it to your desktop again as in section "Preparations". Transfer the operating system image file again as in step 5 of that section but use an additional option: 
++
+[source,bash]
+----
+[…]# cd
+[…]# arm-image-installer --image=Fedora-Server-34-1.2.aarch64.raw.xz --target=rock-pi-4-rk3399 --addkey=~/.ssh/id_mysbc_rsa.pub  --media=/dev/mmcblk0 
+----
++
+When the process has finished, reinstall the CD card in the SBC, and connect to power to start the device again.
++
+Ping the address and as soon as you are connected, use ssh to log in and set a password for root.
++
+[source,bash]
+----
+[…]# ping 192.168.158.120
+[…]# ssh -i .ssh/id_mysbc_rsa  root@192.168.158.120
+[…]# passwd
+----
++
+In your browser open again https://192.168.158.120:9090, login as root using the password as set above, and proceed with section "Final configuration".
+
+
+
 
-The Fedora SBC disk image provides a hard disk size of about 5 gb. This way the distributed image file in raw format does not get too big. As part of the installation process it must get adapted to the local hardware.
 
 

