From 0a6d60f0d96ad3ff0b50d53c036880de9e8086da Mon Sep 17 00:00:00 2001 From: Peter Boy Date: Nov 02 2022 22:01:02 +0000 Subject: Updated installation on SBC --- diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc index c467705..fa1faa0 100644 --- a/docs/modules/ROOT/nav.adoc +++ b/docs/modules/ROOT/nav.adoc @@ -1,7 +1,7 @@ * xref:installation-an-introduction.adoc[Server installation] ** xref:installation-interactive-local.adoc[Interactive local installation] ** xref:installation-interactive-remote.adoc[Interactive remote installation] -** xref:server-installation-sbc.adoc[Server installation on Single Board Computers (SBC)] +** xref:installation-on-sbc.adoc[Installation on a Single Board Computers (SBC)] * xref:sysadmin-an-introduction.adoc[Server Administration] ** xref:sysadmin-postinstall.adoc[Post Installation Tasks] ** xref:sysadmin-dnsmasq.adoc[Setting up dnsmasq – a lightweight DHCP and DNS server] diff --git a/docs/modules/ROOT/pages/installation-on-sbc.adoc b/docs/modules/ROOT/pages/installation-on-sbc.adoc new file mode 100755 index 0000000..26a5f1b --- /dev/null +++ b/docs/modules/ROOT/pages/installation-on-sbc.adoc @@ -0,0 +1,438 @@ += Installation on a Single Board Computer (SBC) +Fredrik Arneving; Peter Boy; Jan Kuparinen +:page-authors: {author}, {author_2}, {author_3} + +[sidebar] +**** +Author: Peter Boy (pboy) | Creation Date: 2021-05-25 | Last update: 2022-11-02 | Related Fedora Version(s): 34-36 +**** + +Fedora Server is also available for Single Board Computers (SBC) like the well-known Raspberry Pi. Even though these devices are very miniature and limited in power, they offer enough strength, to install a dedicated modern, solid server system. This is especially true for the newer alternatives to the Raspberry Pi. Installation works quite different, though. But in the end __Fedora Server works on application level exactly as otherwise familiar__. + +== How it works + +Single board computers originally had only __one data storage medium__, an SD card. And they were equipped with a small, simple build in 'hard wired' first stage boot loader. It is designed to just boot directly from that SD card, expecting a second stage boot loader at a specific address. The device expects a ready-to-use operating system, configured precisely for the respective hardware. + +Therefore, Fedora Server Edition is distributed as a generic aarch64 Fedora Server Edition image file. The installation is simply a matter of _copying this image file_ to an attachable storage medium, traditionally an SD card, while at the same time _making adjustments_ to the specific hardware and some software configurations. + +That original principle is still basically maintained today. +Fedora distributes a generic Fedora Server Edition image, preconfigured for Raspberry Pi. + +== Prerequisites + +=== Fedora compatible Single Board Computer + +Fedora is dedicated and uncompromising Free Software, for good reason. All software involved must be open source and freely available. This applies in particular to the kernel. + +Nearly all SBC models claim to support Linux as operating system. In fact, to even boot, many of them require proprietary software that Fedora cannot and will not distribute. Those models are working with Linux, but only in a proprietary tainted version, customized by the manufacturer. + +_Fedora compatible_ are only those SBCs for whose components to be used either manufacturers contribute open source drivers or community developed drivers are available. It may well be that a specific SBC model is compatible with Fedora Server because, for example, there are free drivers for a text console and wired Ethernet. The same model may not be compatible with Fedora Workstation because drivers for the graphics display, graphics acceleration or WiFi connection are not freely available. + +https://fedoraproject.org/wiki/Architectures/ARM[Arm SIG] provides a list of devices that are operable with Fedora. The Fedora Server Edition is only available for ARMv8/aarch64. + +[WARNING] +==== +When choosing a device for Fedora Server, check carefully if it is actually compatible with Fedora. Even if a board is basically operable, advanced features, e.g. PCIe or SATA interface, may not work. Take everything with a grain of salt. Don't expect everything to work just smoothly in aarch64. It is best to ask in advance on the arm mailing list. +==== + +=== Minimal Requirements + +* As a server it needs a *network connection* ++ +At least a wired connection must be available. + +* *Text based display and keyboard connectors* ++ +The initial configuration at first boot is performed at a local text terminal. + +* A *bootable removable disk* of suitable size ++ +Practically, this is either an SD card or eMMC storage on a removable daughterboard. In special cases, when a UEFI capable SPI is available, booting from USB or other media may also be possible. ++ +The absolute minimum capacity is 8 gb, but avoid anything smaller than 16 gb. Unless you intend to operate a database or e.g. a music library, a capacity of 32 gb should be fine and affordable nowadays. + +=== Initial Equipment + +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. + +=== Fedora Desktop + +Fedora provides a utility to transfer the image to the prospective boot medium, usually an SD or eMMC card. Furthermore, the transfer program configures the generic Fedora Server image for use with a specific included SBC model. Optionally, it can also make some adjustments to the initial configuration. + +And your desktop must be able to write to a SD card, either by a dedicated slot or an USB adapter. + +The utility should be usable with any Linux desktop, but not with Windows or MacOS. + +== Special considerations: Organization of the storage area + +Fedora on SBC hardware uses UEFI as boot system. This distinguishes Fedora from other, less ambitious distributions. It follows the same configuration principles as on fullblown Server Hardware. + +SBC Fedora Server Edition first creates an efi partition and a small /boot partition, used by grub2 bootloader. Thereafter, it creates another partition including one volume group (VG), which provides a logical volume with XFS file system for the operating system and its software. Just as on any other system. The size of the root volume is limited, on fullblown hardware about 15 GB depending on the disk size. The rest is left free for other logical volumes that are to hold user data. + +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. + +Fedora Server Edition implements this principle, which originated in professional IT, on SBCs as well. For practical reasons, the deliverable is limited to just under 8 GB in total. This means that the download file is not excessively large and can be installed even on the smallest SD cards currently available. During or after installation, the size is adjusted to the existing hardware. + +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 a Single Board Computer + +=== Preparations + +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] +---- +[…]# cd ~/Downloads + +[…]# wget http://download.fedoraproject.org/pub/fedora/linux/releases/36/Server/aarch64/images/Fedora-Server-36-1.5.aarch64.raw.xz -O Fedora-Server-36-1.5.aarch64.raw.xz + +[…]# wget https://getfedora.org/static/checksums/36/images/Fedora-Server-36-1.5-aarch64-CHECKSUM -O Fedora-Server-34-1.2-aarch64-CHECKSUM + +[…]# sha256sum -c *-CHECKSUM --ignore-missing +---- ++ +On a Mac (Catalina) use shasum5.28 instead. + + +2. On a Fedora Workstation, install arm-image-installer ++ +[source,bash] +---- +[…]# dnf install arm-image-installer uboot-images-armv8.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: ++ +[source,bash] +---- +[…]# lsblk +NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINT +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 + ├─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] + +[…]# umount /path/to/mountpoint/above +---- ++ +On a Mac open a terminal und issue: ++ +[source,bash] +---- +[…]# diskutil list +/dev/disk0 (internal, physical): + #: TYPE NAME SIZE IDENTIFIER + 0: GUID_partition_scheme *251.0 GB disk0 +... +... +/dev/disk2 (internal, physical): + #: TYPE NAME SIZE IDENTIFIER + 0: FDisk_partition_scheme *31.9 GB disk2 +... +... + +[…]# sudo diskutil unmountDisk /dev/disk2 +---- + +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-36-1.5.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 and to dispense with segmentation, you may add the --resizefs parameter which would result in an _alternative command line_: ++ +[source,bash] +---- +[…]# arm-image-installer --image=Fedora-Server-36-1.5.aarch64.raw.xz --target=rpi4 --resizefs --media=/dev/mmcblk0 +---- ++ +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-36-1.5.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. + + +=== Basic Installation + +Directly at a terminal of the SBC we will make only the minimal, absolutely necessary configuration. This is the setting of a root password and the determination of the IP address. Everything else is done comfortably on our desktop. + +1. Make sure that the Raspberry Pi is disconnected from power. +2. Connect monitor, keyboard and network cable, insert the micro SD card. +3. Connect Raspberry Pi to power and wait. After some time you will be greeted by a very plain configuration screen. +4. If you have a DHCP server on your LAN 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. If you don't have a DHCP server on your LAN type "3" and fill in your hostname and your network details. +6. 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 on reboot again and again conflict with the subsequent configuration. +==== +7. Above the user input, a line with the (temporary) name of the computer and an IP address is displayed. The name is "fedora" by default and the IP address depends on the network. Note both carefully. +8. You can now disconnect monitor and keyboard. The next steps all happen on the desktop. + +=== Final Configuration + +1. On your desktop open a Browser and enter name and port __http://fedora:9090__. Sometimes the internal DNS already works. 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 your SBC appears. ++ +image::serverinstall-sbc-020.png[Cockpit Login Screen] + +2. Login with your root account to continue configuration ++ +image::serverinstall-sbc-030.png[Cockpit Overview Screen] + +3. First *adjust hostname* ++ +Click onto "set hostname" and enter a short name (display name) and a fqdn name. + +4. *Adjust time and time zone* if necessary. Click on system time and select the time zone. Automatic time synchronization should already be enabled. ++ +If a local time server is available in your network, it can be entered here. Many routers offer such a function and relieve the infrastructure. + +5. To be able to access as root via ssh, you have to *install your public ssh key* for root. ++ +Select "accounts" in the left navigation column and choose the root account. At the bottom select "Add Key". Copy&paste your public key into the input field. ++ +If you chose a simple password during the basic installation, you should replace it with a more complex one at this occasion. + +6. If you are non-US you may want to **set your language**. In any case, you should choose the **keyboard layout** correctly. Otherwise, in case of an emergency you may have to use a directly attached monitor and keyboard again, you need a correct mapping to act efficiently. ++ +Select "Terminal" in the left navigation menu. You get a terminal access to your device, already logged in as root. ++ + a. List available languages by "__localectl list-locales__". Find your locale in the list and note the token, e.g. de_DE.UTF-8. Set the language with "__localeectl set-locale LANG=TOKEN__", e.g. "__localeectl set-locale LANG=de_DE.UTF-8__". ++ + b. List available keyboard mappings by "__localectl list-keymaps__". Find your keymap in the list and note the token, e.g. de-nodeadkeys. Set the keymap with "__localectl set-keymap MAP_TOKEN__", e.g. "__localectl set-keymap de-nodeadkeys__". ++ + c. Finally check by "__localeectl__" + +7. Most likely, the packages of the distributed file image are not up to date. In the menu bar on the left, you will probably see an exclamation mark next to "**Software Updates**". Select this menu item. A search for updates starts and after some time a list of updates appears. Select "Install all updates" and sit back. It will take a while. ++ +If the cockpit packages are also updated, the connection is interrupted. You must then reconnect. ++ +With everything done reboot the system. In the overview screen select either reboot or shutdown in the upper right corner. You can now use a shutdown to disconnect keyboard and monitor, if desired. You may also put the device in a different, final place. Start the device afterwards. + +8. When the device is up again it is time to **test the installation**. + 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. + +9. Finally, depending on the use case, you may need to ensure you can always track which person was logged in and when. Use Cockpits account management feature to comfortably create additional users and grant them administrativ permissions ("sudo"). You might want to lock the root account completely (postpone this until storage area configuration is completed). + +== 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. + +3. You may reinforce the rationale of separating system and user data even further and create a separate partition and volume group for user data. This seems a bit far-fetched for a (small) SBC, but is nevertheless worth considering if a very large volume and correspondingly a large amount of data are present (a rule of thumb: larger 500 GB). + +=== Enlarge partition and volume group to fill the disk space + +Any of the alternatives 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 that device name: ++ +[source,bash] +---- +[…]# cfdisk /dev/mmcblk1 +---- +4. Select partition 3 (Type 8e Linux LVM) using and then Resize using ++ +image::serverinstall-sbc-090.png[Partition resize] + +5. The suggested size fills the complete disk. ++ +In case of *alternative 1 or 2* confirm with . ++ +In case of *alternative 3* select a size for system VG, as a rule of thumb at least 10GB, max. 30 GB. ++ +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 rsp. as configured. +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. ++ +For *alternative 3.* select "Grow" and expand the volume to a size that still leaves room for the unanticipated. An initial size for root between 8 and 12 GB 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. + +10. In case of alternative 3 use Cockpits storage to create an additional partition and volume group. + +Later, when you install applications and services you will use Cockpit storage to create logiocal volumes and mount them at the appropriate location. As an example you may create a logical volume "__postgresdata__", create an XFS filesystem and mount it at _/var/lib/pgsql_ before actually installing postgresql. + +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/ +---- ++ +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". + + + + + +