From 031dd8617e442a94a962207ce60cae55b176481d Mon Sep 17 00:00:00 2001 From: Peter Boy Date: Jun 26 2021 19:05:24 +0000 Subject: Synchronized final published versions in stg --- diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc index 609a2db..e8a3bfd 100644 --- a/docs/modules/ROOT/nav.adoc +++ b/docs/modules/ROOT/nav.adoc @@ -6,8 +6,8 @@ ** xref:sysadmin-cockpit.adoc[Cockpit] * xref:server-virtualization.adoc[Virtualization] ** xref:virtualization-install.adoc[Add Virtualization Support] -** xref:virtualization-vminstall.adoc[VM Installation Using Cockpit] -** xref:virtualization-vmcloud.adoc[VM Installation Using Cloud Image] +** xref:virtualization-vm-create-cockpit.adoc[VM Installation Using Cockpit] +** xref:virtualization-vm-cloud.adoc[VM Installation Using Cloud Image] * xref:server-containers.adoc[Containers] ** xref:container-nspawn.adoc[Container systemd-nspawn] * xref:server-usecases.adoc[Example Use Cases] diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc index 6b9805e..d22f2fc 100644 --- a/docs/modules/ROOT/pages/index.adoc +++ b/docs/modules/ROOT/pages/index.adoc @@ -1,67 +1,64 @@ = Fedora Server Documentation -Peter Boy; Jan Kuparinen -:page-authors: {author}, {author_2} +Peter Boy; Jan Kuparinen; Peter W. Smith +:page-authors: {author}, {author_2}, {author_3} image::Logo_server2.png[Server] - [NOTE] ==== -**Beta 1**! Please comment on server mailing list -==== +**Released** Status: current version +==== [sidebar] **** -Creation Date: 2021-03-10 | Last update: 2021-03-28 | Related Fedora Version(s): 34 +Creation Date: 2021-03-10 | Last update: 2021-06-09 | Related Fedora Version(s): 34 **** == Our Mission *As a user, you gain the opportunity to use the server of the future right now.* -Fedora Server provides a stable, flexible and universally adaptable basis for the everyday provision of digital services and information of all kinds by organizations and individuals, based on the latest technology and makes them available as early as possible. - -*As a developer or system integrator, you gain an eye on the server of the future.* +Fedora Server provides a stable, flexible and universally adaptable basis for the everyday provision of digital services and information, suitable for use by all kinds of organizations and individuals. +It is based on the latest technology and as such, brings the most modern environment to users as early as possible. -Fedora Server is a platform for developers and system integrators, which provides an implementation of the latest server technology for further evaluation and practical appropriation. +*As a developer or system integrator, you preview the server of the future.* +Fedora Server is a platform for developers and system integrators, providing an implementation of the latest server technology for further evaluation and practical use. -== What's Cooking +== What's in the Pipeline? -Currently, we work on several projects +Currently, several projects are in development: -- We are preparing Fedora Server 34 -- We are working on improving Server's documentation (you currently get a first glimpse) -- We are exploring opportunities of aligning cloud images and server installation more closely with each other and further harmonizing technical details. -- Technically we are revisiting defaults ... filesystem / partitioning +- Preparations for Fedora Server 35 +- Improvements to the documentation (you're currently getting a preview) +- Facilitation of the deployment of key services by combining rpm and Ansible Stay tuned. The results will soon be visible. - == Why Use Fedora Server -Fedora Server Edition offers users and system administrators several attractive features +Fedora Server Edition offers users and system administrators several attractive features: -* The biannual release cycle allows the inclusion of the latest versions of system and application software almost immediately. This empowers users and system administrators to swiftly respond to new market options and changing or expanding customer requirements. +* *You get the latest software almost immediately*: Fedora Server's biannual release cycle allows for the inclusion of the latest versions of system and application software almost immediately. This empowers users and system administrators to swiftly respond to new market options and changing or expanding customer requirements. -* A sophisticated and highly engineered release and quality assurance process enables a high level of reliability and stability, despite a comparatively fast release cycle. This achieves an excellent balance between 'bleeding edge' and maturity for productive use in mainstream deployments. +* *You can trust it*: Fedora Server has a sophisticated and highly engineered release and quality assurance process, which enables a high level of reliability and stability, despite a comparatively fast release cycle. It therefore achieves an excellent balance between 'bleeding edge' and maturity for productive use in mainstream deployments. -* Enterprise-grade security minded, the Fedora release engineering results in carefully pre-configured releases, offering uncompromising security without prior extensive configuration work by system administrators. +* *Confidence in security*: Enterprise-grade security minded, the Fedora release engineering results in carefully pre-configured releases, offering uncompromising security without prior extensive configuration by system administrators. -* A great variety of available packages, all of them included in that elaborated release process, opens up a wide range of possibilities for building a server very flexibly according to customer specific needs and wishes. +* *You can get what you need*: Fedora Server has an extensive collection of available packages, all of them subject to the same extensive release process. This opens up a wide range of possibilities for building a server very flexibly according to customer specific needs and wishes. -* Inclusion of modern sysadmin tools (i.e. cockpit, dnf, systemd) in their latest stable version noticeably reduces the burden of system administration. +* *It will help ease a sysadmin workload*: Fedora Server includes the latest stable versions of modern sysadmin tools (i.e. cockpit, dnf, systemd), noticeably reducing the burden of system administration. -* Due to the release cycle less disruptive release jumps combine a very easy update process without re-installation requirements, and the option to skip one release jump, in case new capabilities are not immediately needed. Several small updates are easier to manage than a few but big updates. +* *Less disruption with upgrades*: Fedora Server's short release cycle means less disruptive release jumps. There is a very easy update process without re-installation requirements. There is also the option to skip one release cycle in case new capabilities are not immediately needed. Several small updates are easier to manage than a few big updates. -* Utmost freedom from restrictions imposed by commercial interests or corporate feature management and excellent backwards hardware compatibility (including a complete set of standard kernel drivers). +* *You've got the freedom you want*: Fedora Server allows utmost freedom from restrictions imposed by commercial interests or corporate feature management, combined with excellent backward hardware compatibility (including a complete set of standard kernel drivers). -* Developer find an excellent development environment for the next generation server as well as application software with the latest software versions available. +* *Developers will feel right at home*: Fedora Server is an excellent development environment for the next generation server as well as application software with the latest software versions available. == What You Will Find Here - Server installation and administration guides + -You find information about installation and basic system administration supplementing the general Fedora Installation Guide and System Administration Guide. Several other sections cover specific Fedora Server Edition related options and solutions. This includes virtualisation and containerisation in particular. +You find information about installation and basic system administration supplementing the general Fedora Installation Guide and System Administration Guide. Several other sections cover specific Fedora Server Edition related options and solutions. This includes virtualisation and containerization in particular. - Example Use Cases + @@ -69,7 +66,8 @@ Users describe how they use Fedora Server for a wide variety of tasks as well as - Tutorials + -Detailed step-by-step instructions are given for various typical areas of application. They are intended to enable not only experienced system administrators but also inexperienced users to safely install and configure the system. +Detailed step-by-step instructions are given for various typical areas of application. The tutorials are intended to enable not only experienced system administrators but also inexperienced users to safely install and configure the system. + - People, policies, and working methods @@ -82,9 +80,9 @@ You don't have to be a programmer, a developer or a technical nerd to contribute The easiest way is to write on our mailing list. It is a low traffic list specifically for Fedora Server Edition. It is open to everyone. -Another option is our ticket system at https://pagure.io/fedora-server/issues. However, this requires a FAS account. +Another option is our ticket system at https://pagure.io/fedora-server/issues. However, this requires a FAS account, which you can create at link:https://accounts.fedoraproject.org[Fedora accounts] You can also chat with us at -https://webchat.freenode.net/?channels=#fedora-server[#fedora-server] on irc.freenode.net. +https://web.libera.chat/?channels=#fedora-server[#fedora-server] on libera.chat. For additional information refer to https://docs.fedoraproject.org/en-US/fedora-server/server-communicating/[Getting in Touch] diff --git a/docs/modules/ROOT/pages/server-administration.adoc b/docs/modules/ROOT/pages/server-administration.adoc index cc65161..15e0335 100644 --- a/docs/modules/ROOT/pages/server-administration.adoc +++ b/docs/modules/ROOT/pages/server-administration.adoc @@ -1,11 +1,11 @@ = Fedora Server Edition Basic Administration Guide -Peter Boy; Jan Kuparinen -:page-authors: {author}, {author_2} +Peter Boy; Jan Kuparinen; Emmanuel Seyman +:page-authors: {author}, {author_2}, {author_3} [NOTE] ==== -Beta 1 – Please comment on server mailing list! -==== +**Released** Status: current version +==== [sidebar] **** Author: Peter Boy (pboy) | Creation Date: 2021-03-10 | Last update: 2021-03-26 | Related Fedora Version(s): 33,34 @@ -19,13 +19,16 @@ Generic basic system administration is covered by Fedora's overall https://docs As part of the installation, the system is already fitted with many security-relevant configurations. But some items need manual intervention. -First of all, the root account needs a key file to enable secure access via ssh. Right after installation, login as root is not possible due to the (public) key file requirement as configured during installation. +First of all, the root account needs a key file to enable secure access via ssh. Right after installation, a remote login as root via ssh is not possible due to the (public) key file requirement as configured by default during installation. A local password based root login (directly connected terminal, KVM terminal, but su as well) is still enabled in the default configuration. For a number of other procedures, the system manager must weigh the pros and cons and make a decision. This involves, for example -- Installing fail2ban to block IPs with too many unsuccessful logins +- Depending on protection and confidentiality requirements, system-wide disabling root login (system administration is performed exclusively via user accounts with administrative privileges) - Disabling ssh password based login for all users except one (or very few) fallbacks - Protecting Cockpit password terminal login capability +- Installing fail2ban to block IPs with too many unsuccessful logins + +For detailed information see https://docs.fedoraproject.org/en-US/fedora-server/sysadmin-postinstall/[System Administration – Post Installation Tasks] == Cockpit diff --git a/docs/modules/ROOT/pages/server-communicating.adoc b/docs/modules/ROOT/pages/server-communicating.adoc index 27e5fbe..5a4f5bb 100644 --- a/docs/modules/ROOT/pages/server-communicating.adoc +++ b/docs/modules/ROOT/pages/server-communicating.adoc @@ -2,25 +2,24 @@ Peter Boy; Jan Kuparinen :page-authors: {author}, {author_2} +[NOTE] +==== +**Released** Status: current version +==== [sidebar] **** -Author: Jan Kuparinen (copperi) | Creation Date: 2021-03-09 | Last update: N/A | Related Fedora Version(s): All +Author: Jan Kuparinen (copperi) | Creation Date: 2021-03-09 | Last update: 2021-06-09 | Related Fedora Version(s): All **** -[NOTE] -==== -Placeholder! Please comment on server mailing list -==== - - For general troubleshooting help related to Fedora, please refer to link:https://ask.fedoraproject.org[Ask Fedora Forum]. If you found a bug, report it! + * link:https://docs.fedoraproject.org/en-US/quick-docs/howto-file-a-bug/[How to file a bug]. * Issues about a server can be filed at link:https://pagure.io/fedora-server/issues[the ticketing repository on Pagure]. -* You can chat with us at link:https://webchat.freenode.net/?channels=#fedora-server[#fedora-server on irc.freenode.net]. +* You can chat with us at link:https://web.libera.chat/?channels=#fedora-server[#fedora-server on libera.chat]. * You can discuss server issues at link:https://discussion.fedoraproject.org/c/server[Server Discussion Forum]. diff --git a/docs/modules/ROOT/pages/server-faq.adoc b/docs/modules/ROOT/pages/server-faq.adoc index ae7841e..b055f19 100644 --- a/docs/modules/ROOT/pages/server-faq.adoc +++ b/docs/modules/ROOT/pages/server-faq.adoc @@ -2,14 +2,14 @@ Peter Boy; Jan Kuparinen :page-authors: {author}, {author_2} +[NOTE] +==== +**Released** Status: current version +==== [sidebar] **** Author: Jan Kuparinen (copperi) | Creation Date: 2021-03-09 | Last update: N/A | Related Fedora Version(s): All **** -[NOTE] -==== -Placeholder! Please comment on server mailing list -==== [qanda] Can I see a built preview of this template to get a better idea about the result?:: diff --git a/docs/modules/ROOT/pages/server-installation-sbc.adoc b/docs/modules/ROOT/pages/server-installation-sbc.adoc index 61f43eb..f0fe4b5 100644 --- a/docs/modules/ROOT/pages/server-installation-sbc.adoc +++ b/docs/modules/ROOT/pages/server-installation-sbc.adoc @@ -1,11 +1,11 @@ = Installing Fedora Server on Single Board Computers - Raspberry Pi & Co. -Peter Boy; Jan Kuparinen -:page-authors: {author}, {author_2} +Fredrik Arneving; Peter Boy; Jan Kuparinen +:page-authors: {author}, {author_2}, {author_3} [NOTE] ==== -__**– Beta 1 –**__ Please comment on server mailing list! -==== +**Released** Status: current version +==== [sidebar] **** Author: Peter Boy (pboy) | Creation Date: 2021-05-25 | Last update: 2021-05-25 | Related Fedora Version(s): 34 @@ -183,15 +183,16 @@ Directly at a terminal of the SBC we will make only the minimal, absolutely nece 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. 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. +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. Ich 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. ==== -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. +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 @@ -236,6 +237,8 @@ With everything done reboot the system. In the overview screen select either reb 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 @@ -249,13 +252,15 @@ This is the simplest solution and the only sensible one for disks of up to 16gb. + 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 -Alternate 1. and 2. as above start with the same administrative tasks. +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 hat device name: +3. Invoke cfdisk with that device name: + [source,bash] ---- @@ -265,7 +270,14 @@ Alternate 1. and 2. as above start with the same administrative tasks. + image::serverinstall-sbc-090.png[Partition resize] -5. The suggested size fills the complete disk. Confirm with . Select "Write", confirm resizing and quit the program. +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] @@ -274,7 +286,7 @@ image::serverinstall-sbc-090.png[Partition resize] 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. +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] @@ -282,6 +294,8 @@ 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. + @@ -292,6 +306,10 @@ For *alternative 2.* select "Grow" and expand the volume to sensible size. 10gb + 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 == diff --git a/docs/modules/ROOT/pages/server-installation.adoc b/docs/modules/ROOT/pages/server-installation.adoc index a962469..5c9acfc 100644 --- a/docs/modules/ROOT/pages/server-installation.adoc +++ b/docs/modules/ROOT/pages/server-installation.adoc @@ -1,11 +1,11 @@ = Fedora Server Installation Guide -Peter Boy; Jan Kuparinen -:page-authors: {author}, {author_2} +Peter Boy; Kevin Fenzi; Jan Kuparinen +:page-authors: {author}, {author_2}, {author_3} [NOTE] ==== -Status: RC – ready for publication -==== +**Released** Status: current version +==== [sidebar] **** Author: Peter Boy (pboy) | Creation Date: 2021-04-05 | Last update: 2021-04-05 | Related Fedora Version(s): 33,34 diff --git a/docs/modules/ROOT/pages/server-virtualization.adoc b/docs/modules/ROOT/pages/server-virtualization.adoc index 58f4790..9327be8 100644 --- a/docs/modules/ROOT/pages/server-virtualization.adoc +++ b/docs/modules/ROOT/pages/server-virtualization.adoc @@ -1,12 +1,11 @@ = Virtualization -Peter Boy; Jan Kuparinen -:page-authors: {author}, {author_2} - +Fredrik Arneving; Peter Boy; Jan Kuparinen +:page-authors: {author}, {author_2}, {author_3} [NOTE] ==== -**Beta 1**! Please comment on server mailing list -==== +**Released** Status: current version +==== [sidebar] **** Author: Peter Boy (pboy) | Creation Date: 2021-03-31 | Last update: N/A | Related Fedora Version(s): 33,34 diff --git a/docs/modules/ROOT/pages/sysadmin-postinstall.adoc b/docs/modules/ROOT/pages/sysadmin-postinstall.adoc index d7ede83..8a07a9f 100644 --- a/docs/modules/ROOT/pages/sysadmin-postinstall.adoc +++ b/docs/modules/ROOT/pages/sysadmin-postinstall.adoc @@ -1,11 +1,11 @@ = System Administration – Post Installation Tasks -Peter Boy; Jan Kuparinen -:page-authors: {author}, {author_2} +Peter Boy; Kevin Fenzi; Jan Kuparinen +:page-authors: {author}, {author_2}, {author_3} [NOTE] ==== -Status: RC – Ready for publication -==== +**Released** Status: current version +==== [sidebar] **** Author: Peter Boy (pboy) | Creation Date: 2021-04-20 | Last update: 2021-04-26 | Related Fedora Version(s): 33,34 diff --git a/docs/modules/ROOT/pages/virtualization-install.adoc b/docs/modules/ROOT/pages/virtualization-install.adoc index d41149e..7b176f0 100644 --- a/docs/modules/ROOT/pages/virtualization-install.adoc +++ b/docs/modules/ROOT/pages/virtualization-install.adoc @@ -1,10 +1,10 @@ = Adding Virtualization Support -Peter Boy; Jan Kuparinen -:page-authors: {author}, {author_2} +Fredrik Arneving; Peter Boy; Jan Kuparinen +:page-authors: {author}, {author_2}, {author_3} [NOTE] ==== -**Beta 1**! Please comment on server mailing list +**Released** Status: current version ==== [sidebar] **** @@ -17,9 +17,9 @@ Qemu-kvm in combination with Libvirt management toolkit is the standard virtuali QEMU / KVM require hardware virtualization support. The first thing to do is to make sure that it is available. [source,bash] ---- -[…]# grep --color vmx /proc/cpuinfo +[…]# egrep --color 'vmx|svm' /proc/cpuinfo ---- -The output spans multiple lines. Several times 'vmx' must be highlighted in red. If not, you should first check in the BIOS whether virtualization is disabled. +The command will return one line per cpu core if virtualization is enabled. If not, you should first check in the BIOS whether virtualization is disabled. Libvirt stores its data including the image files of the virtual hard disk(s) for the guest systems in /var/lib/libvirt. If you adhere to the default partitioning concept, the libvirt application data is stored in its own logical volume that you have to create in advance. You need to specify the size of the storage area, a unique name, and the accommodating VG (fedora_fedora in case of default partitioning). In the new logical volume, create an xfs file system and mount at /var/lib/libvirt. diff --git a/docs/modules/ROOT/pages/virtualization-vm-cloud.adoc b/docs/modules/ROOT/pages/virtualization-vm-cloud.adoc new file mode 100644 index 0000000..2d5eee1 --- /dev/null +++ b/docs/modules/ROOT/pages/virtualization-vm-cloud.adoc @@ -0,0 +1,458 @@ += Virtual Machines based on Cloud Images +Peter Boy; Jan Kuparinen; +:page-authors: {author}, {author_2} + +[NOTE] +==== +**Released** Status: current version +==== +[sidebar] +**** +Author: Peter Boy (pboy) | Creation Date: N/A | Last update: N/A | Related Fedora Version(s): 33,34 +**** + +As an alternative to using the Fedora Server Edition installation image and installation program, Anaconda, you can use the Fedora Cloud Base image. A base image incorporates a __generic preconfiguration__, as opposed to a cloud platform specific preconfigurations, e.g. Amazon or Google. Fedora Cloud Base Image is a __pre-built Fedora server__, ready to run in a virtual machine. Most distributions offer such an image. So you can use this guideline with adaptations also for a simple installation of a virtual machine with __another distribution__. + +== How it works + +The Cloud image is used directly as ready to use (virtual) system disk in a virtual machine to be created. The first barrier is to perform the necessary initial basic configuration (network connection, root account, etc) so that the VM can start at all and you can log in. In a standard installation this is part of the distribution-specific installer, Anaconda in case of Fedora. In case of a Cloud image there is nothing to install and therefore no installer. Instead, a more or less standardized cloud-specific initialization procedure is used, cloud-init. In the absence of cloud, the system administrator must provide a replacement. The developers of cloud-init fortunately had some foresight and provided a 'nocloud' procedure of that said standardized cloud-specific initialization procedure. As you may guess, in a cloud centric development a nocloud option has a tough time. It remains somewhat of a challenge. + +For an autonomous Fedora server, i.e. not integrated into a cloud or into a development environment such as Vagrant, we use virt-install, the libvirt standard installer. With version 3, as included in Fedora since 33, it provides an easy to use emulation of the cloud-init 'noCloud' procedure. It allows both a very simple installation in a default configuration using a single parameter and a very elaborate configuration using two quite simple configuration files. Before version 3 this was relatively laborious, since a special iso image had to be crafted to inject configuration data. + +== What you get + +In particular, you get time. The workload is significantly lower and correspondingly faster. But by Cloud Base Image you (currently) don’t get an alternatively built but otherwise identical build of Fedora Server Edition. There are some subtle differences. For example, Fedora Server Edition uses xfs as its file system, Cloud Base Image still uses the older ext4. Fedora Server Edition now persists the network configuration completely and stringently in NetworkManager, Cloud Base Image still uses the old ifcfg plugin. Other differences are conceptual. For example, Cloud Image does not install a firewall. This function is usually managed by the cloud system. The use concept for the persistent storage is also different due to technical differences. But overall, the functionality is so far identical and the advantages noticeable that it is worthwhile and makes sense to use it. + +== How to proceed + +First of all you need a working Fedora Server Edition including virtualization support added and libvirtd daemon active. We assume an internal network 'default' with virbr0, DHCP, and DNS set up as well (see section 'Add Virtualization Support'). External network connectivity will be provided by macvlan (ethernet interface) rsp. macvtap (libvirt naming). + +Just a reminder, due to an inconvenience in systemd-resolved implementation in Fedora 33 and 34, you need a separate name service on the host if the host is to be able to address the virtual machines (e.g. dnsmasq). Details are described in the aforementioned guidelines. + +=== Preparations + +1. Fetch a Fedora Cloud Base Image file, here F33, and store it into the directory /var/lib/libvirt/boot, which is the libvirt default location for images to install from by convention. Check the integrity of the download. ++ +[source,] +---- +[…]# wget https://download.fedoraproject.org/pub/fedora/linux/releases/33/Cloud/x86_64/images/Fedora-Cloud-Base-33-1.2.x86_64.qcow2 -O /var/lib/libvirt/boot/Fedora-Cloud-Base-33-1.2.x86_64.qcow2 
 +[…]# wget https://getfedora.org/static/checksums/Fedora-Cloud-33-1.2-x86_64-CHECKSUM -O /var/lib/libvirt/boot/Fedora-Cloud-33-1.2-x86_64-CHECKSUM 
 +[…]# sha256sum --ignore-missing -c *-CHECKSUM +---- ++ +Because the *CHECKSUM file contains the values for all cloud images, we ignore the missing. So the check should result in one OK. + +2. Check the forwarding configuration: ++ +[source,] +---- +[…]# cat /proc/sys/net/ipv4/ip_forward
 +[…]# cat /proc/sys/net/ipv6/conf/default/forwarding +---- ++ +In both cases, an output of value of 1 is required. If necessary, activate forwarding temporarily until next reboot: ++ +[source,] +---- +[…]# echo 1 > /proc/sys/net/ipv4/ip_forward 
 +[…]# echo 1 > /proc/sys/net/ipv6/conf/all/forwarding +---- ++ +For permanent setup create the following file: ++ +[source,] +---- +[…]# vim /etc/sysctl.d/50-enable-forwarding.conf
 +# local customizations
 +#
 +# enable forwarding for dual stack
 +net.ipv4.ip_forwarding=1
 +net.ipv6.conf.all.forwarding=1 +---- ++ +These preparations all done, the external access to the VMs should work flawlessly. + +The virt-install program knows a large number of parameters. Only a few are needed here, which will be explained briefly. + +.Virt-install Parameters +[width="100%"] +|==================== +| --name VM_NAME | Unique name of the VM to install as shown e.g.in VM list +| --memory 3074 | Amount of memory to allocate +| --cpu host --vcpus 3 | same cpu type as host, adjust numbers as appropriate +| --os-type linux | Fix here, used by virt-install to determine defaults +| --os-variant fedora33 | Adjust distribution and version as needed +| --import | Fixed, skips installation procedure and boots from the first (virtual) disk as specified by the first ‐-disk parameter. +| --graphics none | Fixed, enforces a redirect of the VM login prompt to the host terminal window for immediate access. +| --disk /var/lib/libvirt/images/VM_NAME.qcow2, format=qcow2,bus=virtio | disk image file, adjust VM_NAME +| --network direct,source=enpXsY,source_mode=bridge, model=virtio | specify _external_ netwok (macvlan) __first__, it will get the name eth0 as usual. Adjust interface name as appropriate. +| --network bridge=virbr0,model=virtio | specify the _internal_ network (libvirt generated bridge) _second_. It will get the name eth1 as usual. +| --cloud-init | new with version 3 to handle nocloud configuration +|==================== + +=== Installation alternative 1: minimal configuration effort + +This type of installation uses the --cloud-init parameter without any value or subparameters. This approach causes the generation and display of a root password shortly after the start of installation, enabling a one-time login. You have to note or copy it, of course. To get the full benefit, DHCP should be available for all Ethernet interfaces. Otherwise, the interface will be set up, but no connection will be established. Beyond that cloud-init is executed with sensible default settings. Finally, it is deactivated and not executed during subsequent boot processes. + +The installation begins by creating a copy of the download image as a (fully installed) virtual disk in the directory /var/lib/libvirt/images, by convention the virtual disk pool. + +Optionally, the size of the virtual disk can be increased. The default is about 5 GiB. You can resize the virtual disk later, too. Therefore, there is no reason to plan too generously in terms of size now. Due to the qcow2 format resizing does not affect the current image file size. It is dynamically adjusted as needed up to the maximum specified. + +The example below _adds_ 10 GiB to a total size of about 15 GiB. +[source,bash] +---- +[…]# cp /var/lib/libvirt/boot/Fedora-Cloud-Base-33-1.2.x86_64.qcow2 \ + /var/lib/libvirt/images/VM_NAME.qcow2 +[…]# qemu-img resize /var/lib/libvirt/images/VM_NAME.qcow2 +10G +[…]# qemu-img info /var/lib/libvirt/images/VM_NAME.qcow2 +---- + +Thereafter, use the virt-install program to immediately start installation. The parameters pass all the required information. No further intervention, no further preparation is required. + +[source,bash] +---- +[…]# virt-install --name VM_NAME\ + --memory 3074 --cpu host --vcpus 3 --graphics none\ + --os-type linux --os-variant fedora33\ + --import \ + --graphics none \ + --disk /var/lib/libvirt/images/VM_NAME.qcow2,format=qcow2,bus=virtio \ + --network type=direct,source=enp1s0,source_mode=bridge,model=virtio \ + --network bridge=virbr0,model=virtio \ + --cloud-init + +---- +You see a lot of output: +[source,text] +---- +WARNING Defaulting to --cloud-init root-password-generate=yes,disable=yes + +Starting install... +Password for first root login is: OtMQshytI0E8xZGD
 +Installation will continue in 10 seconds (press Enter to skip)... +Connected to Domain: VM_NAM
 +Escape character is ^] (Ctrl + ])
 +[ 0.000000] Linux version … … … +…
 +…
 +…
 +[…] cloud-init[757]: Cloud-init v. 20.4 finished … Datasource DataSourceNoCloudc … +[FAILED] Failed to start Execute cloud user/final scripts.
 +See 'systemctl status cloud-final.service' for details.
 +[ OK ] Reached target Cloud-init target.

 + +Fedora 34 (Cloud Edition)
 +Kernel 5.11.12-300.fc34.x86_64 on an x86_64 (ttyS0) + +localhost login: +---- + +The VM terminal appears when installation is complete. Note that the first root login password is displayed early in the process and is used for the initial login. This password is single use and must be replace during the first login. + +The error message is unsightly, but does not affect operation. It might be the reason for cloud-init service still enabled. You may disable it manually or remove it at all. + +Still on the host you may check the network status: +[source,bash] +---- +[…]# less /var/lib/libvirt/dnsmasq/virbr0.status
 + +[ + { + "ip-address": "192.168.122.109", + "mac-address": "52:54:00:57:35:3d", + "client-id": "01:52:54:00:57:35:3d", + "expiry-time": 1615665342 + }
 +] +---- +As you see, the VM got an internal IP, but no hostname because no one has been set until now. That is one of the post-installation tasks to perform. + +==== Post-Installation Tasks + +The initially displayed password enables a login and forces the setting of a new one. + +Of particular interest is the network configuration. +---- +# ip a + + +---- +If DHCP was available, a complete interface configuration is displayed. + +Check for connectivity: +[source,bash] +---- +# ping host +# ping host.example.lan +# ping host.example.com +# ping guardian.co.uk +---- +The VM can connect to internal and external destinations. The name resolution for the vm itself can't work because the static hostname is not set yet. + +The network configuration is stored in /etc/sysconfig/network-scripts. There is only a file for the first, external interface. The internal interface to libvirt virbr0 is generated with every boot process. + +In case the virtual disk size has been changed, the partition sizes must be adjusted. +[source,bash] +---- +[…]# cfdisk /dev/vda +---- +The only partition should already have the adjusted size. Otherwise select resize and then write. + +What remains is the resizing of the file system. +[source,bash] +---- +[…]# resize2fs -p /dev/vda1 +---- + +Finally, let's set the hostname +[source,bash] +---- +[…]# hostnamectl set-hostname VM_NAME.example.lan +---- + +Exit and close the console by +]. + +You may reboot the VM and than check /var/lib/libvirt/dnsmasq/virbr0.status again. It’s now listing a hostname, internal name resolution is working now. + +If your external DHCP server provides dynamic DNS as well, you should be able to connect to your VM from the public network: +[source,batch] +---- +[…]# ping VM_NAME.example.com +---- + +Last action is to enable autostart of the VM. +[source,] +---- +[…]# virsh autostart VM_NAME +---- + +Everything is working fine now, nearly out of the box. You would now start configuring the VM in detail according to its intended use. Just as it would be required after a standard installation. + +*In the end it takes only some 5 minutes to set up a fully functional system with minimal effort.* It is ideal to quickly create a virtual machine for an ad-hoc solution or as an interim solution for a test. + +And it is the ideal way to install a __Cloud Base Image of another distribution__, which may differ in detail from Fedora Cloud Base Image and its elaborate configuration as below. This sets the *stage for tailoring an elaborate configuration of another guest distribution* as described below for Fedora. + +=== Installation alternative 2: elaborate configuration effort + +Usually, a VM is more complex and there are several issues to deal with. There is a public facing interface that requires a firewall that is not included in the Fedora Cloud Base image. You have either to configure the host to protect the VM or install a firewall. Furthermore it is a peculiarity of the cloud-init process that the second, internal interface is not configured persistently. Instead, it is set up anew each time the system is booted. This makes it impossible to assign a firewall zone to this interface. The public interface also provides ssh access. So a root key file is needed to secure the login. + +As soon as multiple VMs are to be installed, the above installation alternative 1 gets quite repetitive and requires a considerable amount of time. Instead, the cloud-init procedure can get detailed configuration information by 2 configuration files, meta-data and user-data. These files can be passed by reference via 2 subparameters of --cloud-init. + +While you are free where to store these files, the boot directory is the preferred location, e.g. a subdirectory …/boot/cloud-init. + +==== Preparing meta-data + +The file referenced by *_meta-data_* contains information about the runtime environment, including a static network configuration, if required. Here only the mandatory parameter instance-id is filled in, which must be unique in a cloud environment, but can be chosen arbitrarily in a nocloud environment. +[source,] +---- +[…]# mkdir /var/lib/libvirt/boot/cloud-init 
 +[…]# vim /var/lib/libvirt/boot/cloud-init/meta-data 
 +instance-id: myapp +---- +According to specifications a static network connection may get configured in meta-data. Basically it works. But some – obviously long standing – bugs require manual intervention in any case. So it is easier to configure a static network by adjusting the default initialization in the other, custom specific file user-data. + +==== Preparing user-data + +That file, referenced by **__user-data__**, holds the main configuration work. The tool is very powerful. Just about all configuration work that an administrator would perform to configure a server in detail can be recorded here. +Configuration includes several steps. + +1. Setting the hostname +2. Set up the user root, the public SSH key is copied into the file as well as set up the fallback account "hostmin" (or alike) which should also be able to log in by password. It will be assigned to the group wheel and his public key will be copied into the file +3. Set up a first-time password for both users for initial login and to be changed immediately +4. Install required additional packages, e.g. the firewall, fail2ban, postfix (needed by fail2ban) and custom specific software, maybe a webserver +5. Some packages need additional configuration files +6. The VM needs an update of all packages +7. Several configuration commands are required +a. Optional: convert interface eth0 to static +b. Assign zone trusted to the interface eth1 (2nd position in the dbus path, so the order of the network parameters when calling libvirt is crucial!) and rename it according to naming convention. The modification also persists to a configuration file (still in /etc/sysconfig/network-scripts/ ) +c. Start the firewall and add required services +d. If the size of the virtual disk has been changed, the file system must be updated. +e. Finally disable cloud-init + +The first line must necessarily contain some kind of shebang, which cloud-init uses to determine the format of the following data. The formatting itself is yaml. +[source,] +---- +[…]# vim /var/lib/libvirt/boot/cloud-init/user-data +#cloud-config + +# (1) setting hostname +preserve_hostname: False
 +hostname: VM_NAME
 +fqdn: VM_NAME.EXAMPLE.COM + +# (2) set up root and fallback account including rsa key copied into this file +users: + - name: root + ssh_authorized_keys:
 + - ssh-rsa AAAAB3NzaC1yc2EAAAADAQA...jSMt9rC4uKDPR8whgw== + + - name: hostmin + groups: users,wheel + ssh_pwauth: True + ssh_authorized_keys: + - ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAIAQDix...Mt9rC4uKDPR8whgw== + +# (3) set up a first-time password for both accounts
 +chpasswd: + list: | + root:MY_PASSWORD + hostmin:TOP_SECRET + expire: True + +# (4) install additional required packages +packages: + - firewalld + - postfix + - fail2ban + - vim + - letsencrypt + +# (5) some packages need additional configuration files
write_files: + - path: /etc/fail2ban/jail.local + content: | + # /etc/fail2ban/jail.local + # Jail configuration additions for local installation + + # Adjust the default configuration's default values + [DEFAULT] + ##ignoreip = /24 /32 + bantime = 6600 + backend = auto + + # The main configuration file defines all services but + # deactivates them by default. We have to activate those neeeded + [sshd] + enabled = true + +# (6) perform a package upgrade
 +package_upgrade: true + +# (7) several configuration commands are executed on first boot +runcmd: + # (a) If needed, convert interface eth0 as static + # IMPORTANT: external interface eth0 have to be specified + # BEFORE internal eth1 in virt-instal option list + # comment in and modify as required + ##- nmcli con mod path 1 ipv4.method static ipv4.addresses '/24' + ##- nmcli con mod path 1 ipv4.gateway '' ipv4.dns '' + ##- nmcli con mod path 1 ipv6.method static ipv6.addresses '/64' + ##- nmcli con mod path 1 ipv6.gateway '' ipv6.dns '' + ##- nmcli con up path 1 + # + # (b) assign a zone to internal interface as well as some other adaptations. + # results in the writing of a configuration file + # IMPORTANT: internal interface have to be specified SECOND after external + - nmcli con mod path 2 con-name eth1 connection.zone trusted + - nmcli con mod path 2 ipv6.method disabled + - nmcli con up path 2 + + # (c) activate and configure firewall and additional services + - systemctl enable firewalld --now + - systemctl enable fail2ban --now + + # (d) try to grow partition and filesystem just in case disk was enlarged + # Does no harm if not. + - growpart /dev/vda 1 + - resize2fs -p /dev/vda1 + + # (e) finally disable cloud-init and reboot + - systemctl disable cloud-init + - reboot +# done +---- + +A concentrated overview of the user-data configuration options provides the examples section of the https://cloudinit.readthedocs.io/en/latest/topics/examples.html[cloud-init project documentation]. + +==== Launch installation + +After the configuration files are created, the virt-install process can be initiated. First copy the downloaded Cloud Image file and optionally adjust the virtual disk size. +[source,bash] +---- +[…]# cp /var/lib/libvirt/boot/Fedora-Cloud-Base-33-1.2.x86_64.qcow2 \ + /var/lib/libvirt/images/VM_NAME.qcow2 +[…]# qemu-img resize /var/lib/libvirt/images/VM_NAME.qcow2 +10G +[…]# qemu-img info /var/lib/libvirt/images/VM_NAME.qcow2 +---- +Execute virt-install and adjust the values of CPU, memory, external network interface etc. to the requirements! +[source,bash] +---- +[…]# virt-install --name VM_NAME \ + --memory 3074 --cpu host --vcpus 3 --graphics none \ + --os-type linux --os-variant fedora33 \ + --import \ + --graphics none \ + --disk /var/lib/libvirt/images/VM_NAME.qcow2,format=qcow2,bus=virtio \ + --network type=direct,source=enpXsY,source_mode=bridge,model=virtio \ + --network bridge=virbr0,model=virtio \ + --cloud-init meta-data=/var/lib/libvirt/boot/cloud-init/meta-data,user-data=/var/lib/libvirt/boot/cloud-init/user-data +---- +It takes some time, be patient. After a while a login prompt is shown. Don’t try to login immediately. After some seconds the initialization process will continue. Finally, you see a message like +[source,text] +---- +... +[ OK ] Finished Network Manager Wait Online. +[ OK ] Reached target Network is Online. + +Fedora 34 (Cloud Edition) +Kernel 5.11.12-300.fc34.x86_64 on an x86_64 (ttyS0) + +eth0: 192.168.yyy.zzz 2003:ca:xxxx:yyyy:zzzz:aa:bb:cc +eth1: 192.168.mmm.nnn +my-vm login: +---- + +If the network environment issues IP addresses based on MAC addresses via DHCP, add to the the first network configuration the MAC address: +[source,text] +---- +--network type=direct,source=enpXsY,source_mode=bridge,mac=52:54:00:aa:bb:cc,model=virtio +---- + +Remember, that the first 3 pairs in the MAC address must be the sequence '52:54:00' for KVM virtual machines. + +==== Check installation + +Finally, login and check the installation. All interfaces should be up and running. +[source,bash] +---- +[…]# ip a +---- + +Name resolution should work without further configuration +[source,bash] +---- +[…]# resolvectl domain + Global: + Link 2 (eth0): ~. + Link 3 (eth1): .lan +[…]# resolvectl dns + Global: + Link 2 (eth0): 213.133.98.98 2a01:4f8:0:1::add:1010 + Link 3 (eth1): 192.168.122.1 +---- + +You should be able to connect to internal and external destinations +[source,bash] +---- +[…]# ping .lan +[…]# ping +[…]# ping6 +---- + +Everything should work flawlessly. + +Back on host finally enable autostart of the VM +[source,bash] +---- +[…]# virsh autostart VM_NAME + +---- +Everything done now. + +=== Conclusion + +Configuring the cloud-init process by virt-install version 3 is highly efficient and flexible. You may create a dedicated set of files for each VM or you may keep one set of generic files and adjust them by commenting in and out as required. A combination of both can be use. You can quickly and easily change configuration settings to test suitability for your purposes. + +Thus, a +configuration process is initiated quite comfortably that would otherwise be quite time-consuming. It is this performance that makes the use of cloud images so attractive. + +In summary, the use of Cloud Base Images comes with some inconveniences and suffers from shortcomings in documentation, overall the combination of Cloud Base Images and virt-install version 3 is a great combination for creating virtual machines for Fedora Server Edition. \ No newline at end of file diff --git a/docs/modules/ROOT/pages/virtualization-vm-create-cockpit.adoc b/docs/modules/ROOT/pages/virtualization-vm-create-cockpit.adoc new file mode 100644 index 0000000..f841142 --- /dev/null +++ b/docs/modules/ROOT/pages/virtualization-vm-create-cockpit.adoc @@ -0,0 +1,82 @@ += Create Virtual Machines with Cockpit +Peter Boy; Jan Kuparinen +:page-authors: {author}, {author_2} + +[NOTE] +==== +__** – Work in Progress –**__ Please comment on server mailing list +==== +[sidebar] +**** +Author: Peter Boy (pboy) | Creation Date: N/A | Last update: N/A | Related Fedora Version(s): 33,34 +**** + +Fedora Server is designed as a "headless" system, i.e. it does not have an elaborate graphical user interface and corresponding hardware. Only a simple text console is available. All work on the machine must therefore be done via the command line. + +Cockpit offers an alternative "remote" graphical interface. It operates in the web browser of the system administrator's desktop and executes the required commands on the server on behalf of them. + +== Why Cockpit + +First hand, Cockpit saves the memorization of the complex parameter zoo of __virt-install__, the CLI installation tool. It saves long typing on the keyboard including the correction of accidental typos. But even those who 'speak __virt-install__' fluently can benefit from Cockpit. It automatically provides a lot of status information about configuration and resource usage, which you would otherwise have to collect manually. And this information is always present, no need to keep this information in mind. + +== Using Cockpit to create a Virtual Machine + +Open Cockpit on the host system and log in as root or with your administrative account. Select "Virtual Machines" in the left navigation column. + +image::virtualization-vm-create-cockpit-001.png[Cockpit Create Virtual Machines Overview] + +If there is no tab "Virtual Machines" the corresponding Cockpit module, cockpit-machines-244.1-1.fc34.noarch in case of Fedora 34, is not installed yet. Select "Terminal" and install the module. Restart Cockpit. +[source,] +---- +[...]# dnf install cockpit-machines +---- + +In the upper left corner: Storage Pool + +In the upper right corner: Network, By default: libvirt virbr0 + +In the center: List of virtual machines installed. It is empty when you invoke Cockpit the first time (and not have used another creation method before). + +You see 2 Buttons. "__Create VM__" and "__Import VM__" + +* *Create VM* ++ +Uses an installation program to set up a virtual machine from distribution files, including the creation of a complete OS file system. ++ +You have options: + +** *Download an OS* ++ +You just select an operating system, not just Fedora but also other distributions, and Cockpit selects anything else. It downloads the necessary files and starts the distribution specific installation program. ++ +In case of Fedora there is no option Server but just a release specification. It uses the "everything" ISO which is not recommended for server installation. + +** *Cloud base image* ++ +(Description tbd) + +** *Local install media (ISO image or distro install tree)* ++ +That is the classical way to download an ISO file and boot a virtual machine. Anaconda is started to perform the installation. ++ +If differs from _Download an OS_ that you determine the ISO oder distribution tree to use. + +** *URL (ISO image or distro install tree)* ++ +Basically the same as 'Local install media' but Cockpit performs the download. + +** *Network boot (PXE)* ++ +Uses an existing PWE boot installation. + +* *Import VM* ++ +Uses an exiting and working OS file system disk image and just creates the necessary KVM virtual machine definitions. + +=== Create a new virtual maching using a distro installation media + +In either of the three installation types 'Download OS' 'Local install media' and 'URL' an (nearly) indentical input form opens to enter the requirred configuration specification/information. + + + + diff --git a/docs/modules/ROOT/pages/virtualization-vmcloud.adoc b/docs/modules/ROOT/pages/virtualization-vmcloud.adoc deleted file mode 100644 index 74ecb5d..0000000 --- a/docs/modules/ROOT/pages/virtualization-vmcloud.adoc +++ /dev/null @@ -1,458 +0,0 @@ -= Virtual Machines based on Cloud Images -Peter Boy; Jan Kuparinen -:page-authors: {author}, {author_2} - -[NOTE] -==== -**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): 33,34 -**** - -As an alternative to using the Fedora Server Edition installation image and installation program, Anaconda, you can use the Fedora Cloud Base image. A base image incorporates a __generic preconfiguration__, as opposed to a cloud platform specific preconfigurations, e.g. Amazon or Google. Fedora Cloud Base Image is a __pre-built Fedora server__, ready to run in a virtual machine. Most distributions offer such an image. So you can use this guideline with adaptations also for a simple installation of a virtual machine with __another distribution__. - -== How it works - -The Cloud image is used directly as ready to use (virtual) system disk in a virtual machine to be created. The first barrier is to perform the necessary initial basic configuration (network connection, root account, etc) so that the VM can start at all and you can log in. In a standard installation this is part of the distribution-specific installer, Anaconda in case of Fedora. In case of a Cloud image there is nothing to install and therefore no installer. Instead, a more or less standardized cloud-specific initialization procedure is used, cloud-init. In the absence of cloud, the system administrator must provide a replacement. The developers of cloud-init fortunately had some foresight and provided a 'nocloud' procedure of that said standardized cloud-specific initialization procedure. As you may guess, in a cloud centric development a nocloud option has a tough time. It remains somewhat of a challenge. - -For an autonomous Fedora server, i.e. not integrated into a cloud or into a development environment such as Vagrant, we use virt-install, the libvirt standard installer. With version 3, as included in Fedora since 33, it provides an easy to use emulation of the cloud-init 'noCloud' procedure. It allows both a very simple installation in a default configuration using a single parameter and a very elaborate configuration using two quite simple configuration files. Before version 3 this was relatively laborious, since a special iso image had to be crafted to inject configuration data. - -== What you get - -In particular, you get time. The workload is significantly lower and correspondingly faster. But by Cloud Base Image you (currently) don’t get an alternatively built but otherwise identical build of Fedora Server Edition. There are some subtle differences. For example, Fedora Server Edition uses xfs as its file system, Cloud Base Image still uses the older ext4. Fedora Server Edition now persists the network configuration completely and stringently in NetworkManager, Cloud Base Image still uses the old ifcfg plugin. Other differences are conceptual. For example, Cloud Image does not install a firewall. This function is usually managed by the cloud system. The use concept for the persistent storage is also different due to technical differences. But overall, the functionality is so far identical and the advantages noticeable that it is worthwhile and makes sense to use it. - -== How to proceed - -First of all you need a working Fedora Server Edition including virtualization support added and libvirtd daemon active. We assume an internal network 'default' with virbr0, DHCP, and DNS set up as well (see section 'Add Virtualization Support'). External network connectivity will be provided by macvlan (ethernet interface) rsp. macvtap (libvirt naming). - -Just a reminder, due to an inconvenience in systemd-resolved implementation in Fedora 33 and 34, you need a separate name service on the host if the host is to be able to address the virtual machines (e.g. dnsmasq). Details are described in the aforementioned guidelines. - -=== Preparations - -1. Fetch a Fedora Cloud Base Image file, here F33, and store it into the directory /var/lib/libvirt/boot, which is the libvirt default location for images to install from by convention. Check the integrity of the download. -+ -[source,] ----- -[…]# wget https://download.fedoraproject.org/pub/fedora/linux/releases/33/Cloud/x86_64/images/Fedora-Cloud-Base-33-1.2.x86_64.qcow2 -O /var/lib/libvirt/boot/Fedora-Cloud-Base-33-1.2.x86_64.qcow2 
 -[…]# wget https://getfedora.org/static/checksums/Fedora-Cloud-33-1.2-x86_64-CHECKSUM -O /var/lib/libvirt/boot/Fedora-Cloud-33-1.2-x86_64-CHECKSUM 
 -[…]# sha256sum --ignore-missing -c *-CHECKSUM ----- -+ -Because the *CHECKSUM file contains the values for all cloud images, we ignore the missing. So the check should result in one OK. - -2. Check the forwarding configuration: -+ -[source,] ----- -[…]# cat /proc/sys/net/ipv4/ip_forward
 -[…]# cat /proc/sys/net/ipv6/conf/default/forwarding ----- -+ -In both cases, an output of value of 1 is required. If necessary, activate forwarding temporarily until next reboot: -+ -[source,] ----- -[…]# echo 1 > /proc/sys/net/ipv4/ip_forward 
 -[…]# echo 1 > /proc/sys/net/ipv6/conf/all/forwarding ----- -+ -For permanent setup create the following file: -+ -[source,] ----- -[…]# vim /etc/sysctl.d/50-enable-forwarding.conf
 -# local customizations
 -#
 -# enable forwarding for dual stack
 -net.ipv4.ip_forwarding=1
 -net.ipv6.conf.all.forwarding=1 ----- -+ -These preparations all done, the external access to the VMs should work flawlessly. - -The virt-install program knows a large number of parameters. Only a few are needed here, which will be explained briefly. - -.Virt-install Parameters -[width="100%"] -|==================== -| --name VM_NAME | Unique name of the VM to install as shown e.g.in VM list -| --memory 3074 | Amount of memory to allocate -| --cpu host --vcpus 3 | same cpu type as host, adjust numbers as appropriate -| --os-type linux | Fix here, used by virt-install to determine defaults -| --os-variant fedora33 | Adjust distribution and version as needed -| --import | Fixed, skips installation procedure and boots from the first (virtual) disk as specified by the first ‐-disk parameter. -| --graphics none | Fixed, enforces a redirect of the VM login prompt to the host terminal window for immediate access. -| --disk /var/lib/libvirt/images/VM_NAME.qcow2, format=qcow2,bus=virtio | disk image file, adjust VM_NAME -| --network direct,source=enpXsY,source_mode=bridge, model=virtio | specify _external_ netwok (macvlan) __first__, it will get the name eth0 as usual. Adjust interface name as appropriate. -| --network bridge=virbr0,model=virtio | specify the _internal_ network (libvirt generated bridge) _second_. It will get the name eth1 as usual. -| --cloud-init | new with version 3 to handle nocloud configuration -|==================== - -=== Installation alternative 1: minimal configuration effort - -This type of installation uses the --cloud-init parameter without any value or subparameters. This approach causes the generation and display of a root password shortly after the start of installation, enabling a one-time login. You have to note or copy it, of course. To get the full benefit, DHCP should be available for all Ethernet interfaces. Otherwise, the interface will be set up, but no connection will be established. Beyond that cloud-init is executed with sensible default settings. Finally, it is deactivated and not executed during subsequent boot processes. - -The installation begins by creating a copy of the download image as a (fully installed) virtual disk in the directory /var/lib/libvirt/images, by convention the virtual disk pool. - -Optionally, the size of the virtual disk can be increased. The default is about 5 GiB. You can resize the virtual disk later, too. Therefore, there is no reason to plan too generously in terms of size now. Due to the qcow2 format resizing does not affect the current image file size. It is dynamically adjusted as needed up to the maximum specified. - -The example below _adds_ 10 GiB to a total size of about 15 GiB. -[source,bash] ----- -[…]# cp /var/lib/libvirt/boot/Fedora-Cloud-Base-33-1.2.x86_64.qcow2 \ - /var/lib/libvirt/images/VM_NAME.qcow2 -[…]# qemu-img resize /var/lib/libvirt/images/VM_NAME.qcow2 +10G -[…]# qemu-img info /var/lib/libvirt/images/VM_NAME.qcow2 ----- - -Thereafter, use the virt-install program to immediately start installation. The parameters pass all the required information. No further intervention, no further preparation is required. - -[source,bash] ----- -[…]# virt-install --name VM_NAME\ - --memory 3074 --cpu host --vcpus 3 --graphics none\ - --os-type linux --os-variant fedora33\ - --import \ - --graphics none \ - --disk /var/lib/libvirt/images/VM_NAME.qcow2,format=qcow2,bus=virtio \ - --network type=direct,source=enp1s0,source_mode=bridge,model=virtio \ - --network bridge=virbr0,model=virtio \ - --cloud-init - ----- -You see a lot of output: -[source,text] ----- -WARNING Defaulting to --cloud-init root-password-generate=yes,disable=yes - -Starting install... -Password for first root login is: OtMQshytI0E8xZGD
 -Installation will continue in 10 seconds (press Enter to skip)... -Connected to Domain: VM_NAM
 -Escape character is ^] (Ctrl + ])
 -[ 0.000000] Linux version … … … -…
 -…
 -…
 -[…] cloud-init[757]: Cloud-init v. 20.4 finished … Datasource DataSourceNoCloudc … -[FAILED] Failed to start Execute cloud user/final scripts.
 -See 'systemctl status cloud-final.service' for details.
 -[ OK ] Reached target Cloud-init target.

 - -Fedora 34 (Cloud Edition)
 -Kernel 5.11.12-300.fc34.x86_64 on an x86_64 (ttyS0) - -localhost login: ----- - -The VM terminal appears when installation is complete. Note that the first root login password is displayed early in the process and is used for the initial login. This password is single use and must be replace during the first login. - -The error message is unsightly, but does not affect operation. It might be the reason for cloud-init service still enabled. You may disable it manually or remove it at all. - -Still on the host you may check the network status: -[source,bash] ----- -[…]# less /var/lib/libvirt/dnsmasq/virbr0.status
 - -[ - { - "ip-address": "192.168.122.109", - "mac-address": "52:54:00:57:35:3d", - "client-id": "01:52:54:00:57:35:3d", - "expiry-time": 1615665342 - }
 -] ----- -As you see, the VM got an internal IP, but no hostname because no one has been set until now. That is one of the post-installation tasks to perform. - -==== Post-Installation Tasks - -The initially displayed password enables a login and forces the setting of a new one. - -Of particular interest is the network configuration. ----- -# ip a - - ----- -If DHCP was available, a complete interface configuration is displayed. - -Check for connectivity: -[source,bash] ----- -# ping host -# ping host.example.lan -# ping host.example.com -# ping guardian.co.uk ----- -The VM can connect to internal and external destinations. The name resolution for the vm itself can't work because the static hostname is not set yet. - -The network configuration is stored in /etc/sysconfig/network-scripts. There is only a file for the first, external interface. The internal interface to libvirt virbr0 is generated with every boot process. - -In case the virtual disk size has been changed, the partition sizes must be adjusted. -[source,bash] ----- -[…]# cfdisk /dev/vda ----- -The only partition should already have the adjusted size. Otherwise select resize and then write. - -What remains is the resizing of the file system. -[source,bash] ----- -[…]# resize2fs -p /dev/vda1 ----- - -Finally, let's set the hostname -[source,bash] ----- -[…]# hostnamectl set-hostname VM_NAME.example.lan ----- - -Exit and close the console by +]. - -You may reboot the VM and than check /var/lib/libvirt/dnsmasq/virbr0.status again. It’s now listing a hostname, internal name resolution is working now. - -If your external DHCP server provides dynamic DNS as well, you should be able to connect to your VM from the public network: -[source,batch] ----- -[…]# ping VM_NAME.example.com ----- - -Last action is to enable autostart of the VM. -[source,] ----- -[…]# virsh autostart VM_NAME ----- - -Everything is working fine now, nearly out of the box. You would now start configuring the VM in detail according to its intended use. Just as it would be required after a standard installation. - -*In the end it takes only some 5 minutes to set up a fully functional system with minimal effort.* It is ideal to quickly create a virtual machine for an ad-hoc solution or as an interim solution for a test. - -And it is the ideal way to install a __Cloud Base Image of another distribution__, which may differ in detail from Fedora Cloud Base Image and its elaborate configuration as below. This sets the *stage for tailoring an elaborate configuration of another guest distribution* as described below for Fedora. - -=== Installation alternative 2: elaborate configuration effort - -Usually, a VM is more complex and there are several issues to deal with. There is a public facing interface that requires a firewall that is not included in the Fedora Cloud Base image. You have either to configure the host to protect the VM or install a firewall. Furthermore it is a peculiarity of the cloud-init process that the second, internal interface is not configured persistently. Instead, it is set up anew each time the system is booted. This makes it impossible to assign a firewall zone to this interface. The public interface also provides ssh access. So a root key file is needed to secure the login. - -As soon as multiple VMs are to be installed, the above installation alternative 1 gets quite repetitive and requires a considerable amount of time. Instead, the cloud-init procedure can get detailed configuration information by 2 configuration files, meta-data and user-data. These files can be passed by reference via 2 subparameters of --cloud-init. - -While you are free where to store these files, the boot directory is the preferred location, e.g. a subdirectory …/boot/cloud-init. - -==== Preparing meta-data - -The file referenced by *_meta-data_* contains information about the runtime environment, including a static network configuration, if required. Here only the mandatory parameter instance-id is filled in, which must be unique in a cloud environment, but can be chosen arbitrarily in a nocloud environment. -[source,] ----- -[…]# mkdir /var/lib/libvirt/boot/cloud-init 
 -[…]# vim /var/lib/libvirt/boot/cloud-init/meta-data 
 -instance-id: myapp ----- -According to specifications a static network connection may get configured in meta-data. Basically it works. But some – obviously long standing – bugs require manual intervention in any case. So it is easier to configure a static network by adjusting the default initialization in the other, custom specific file user-data. - -==== Preparing user-data - -That file, referenced by **__user-data__**, holds the main configuration work. The tool is very powerful. Just about all configuration work that an administrator would perform to configure a server in detail can be recorded here. -Configuration includes several steps. - -1. Setting the hostname -2. Set up the user root, the public SSH key is copied into the file as well as set up the fallback account "hostmin" (or alike) which should also be able to log in by password. It will be assigned to the group wheel and his public key will be copied into the file -3. Set up a first-time password for both users for initial login and to be changed immediately -4. Install required additional packages, e.g. the firewall, fail2ban, postfix (needed by fail2ban) and custom specific software, maybe a webserver -5. Some packages need additional configuration files -6. The VM needs an update of all packages -7. Several configuration commands are required -a. Optional: convert interface eth0 to static -b. Assign zone trusted to the interface eth1 (2nd position in the dbus path, so the order of the network parameters when calling libvirt is crucial!) and rename it according to naming convention. The modification also persists to a configuration file (still in /etc/sysconfig/network-scripts/ ) -c. Start the firewall and add required services -d. If the size of the virtual disk has been changed, the file system must be updated. -e. Finally disable cloud-init - -The first line must necessarily contain some kind of shebang, which cloud-init uses to determine the format of the following data. The formatting itself is yaml. -[source,] ----- -[…]# vim /var/lib/libvirt/boot/cloud-init/user-data -#cloud-config - -# (1) setting hostname -preserve_hostname: False
 -hostname: VM_NAME
 -fqdn: VM_NAME.EXAMPLE.COM - -# (2) set up root and fallback account including rsa key copied into this file -users: - - name: root - ssh_authorized_keys:
 - - ssh-rsa AAAAB3NzaC1yc2EAAAADAQA...jSMt9rC4uKDPR8whgw== - - - name: hostmin - groups: users,wheel - ssh_pwauth: True - ssh_authorized_keys: - - ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAIAQDix...Mt9rC4uKDPR8whgw== - -# (3) set up a first-time password for both accounts
 -chpasswd: - list: | - root:MY_PASSWORD - hostmin:TOP_SECRET - expire: True - -# (4) install additional required packages -packages: - - firewalld - - postfix - - fail2ban - - vim - - letsencrypt - -# (5) some packages need additional configuration files
write_files: - - path: /etc/fail2ban/jail.local - content: | - # /etc/fail2ban/jail.local - # Jail configuration additions for local installation - - # Adjust the default configuration's default values - [DEFAULT] - ##ignoreip = /24 /32 - bantime = 6600 - backend = auto - - # The main configuration file defines all services but - # deactivates them by default. We have to activate those neeeded - [sshd] - enabled = true - -# (6) perform a package upgrade
 -package_upgrade: true - -# (7) several configuration commands are executed on first boot -runcmd: - # (a) If needed, convert interface eth0 as static - # IMPORTANT: external interface eth0 have to be specified - # BEFORE internal eth1 in virt-instal option list - # comment in and modify as required - ##- nmcli con mod path 1 ipv4.method static ipv4.addresses '/24' - ##- nmcli con mod path 1 ipv4.gateway '' ipv4.dns '' - ##- nmcli con mod path 1 ipv6.method static ipv6.addresses '/64' - ##- nmcli con mod path 1 ipv6.gateway '' ipv6.dns '' - ##- nmcli con up path 1 - # - # (b) assign a zone to internal interface as well as some other adaptations. - # results in the writing of a configuration file - # IMPORTANT: internal interface have to be specified SECOND after external - - nmcli con mod path 2 con-name eth1 connection.zone trusted - - nmcli con mod path 2 ipv6.method disabled - - nmcli con up path 2 - - # (c) activate and configure firewall and additional services - - systemctl enable firewalld --now - - systemctl enable fail2ban --now - - # (d) try to grow partition and filesystem just in case disk was enlarged - # Does no harm if not. - - growpart /dev/vda 1 - - resize2fs -p /dev/vda1 - - # (e) finally disable cloud-init and reboot - - systemctl disable cloud-init - - reboot -# done ----- - -A concentrated overview of the user-data configuration options provides the examples section of the https://cloudinit.readthedocs.io/en/latest/topics/examples.html[cloud-init project documentation]. - -==== Launch installation - -After the configuration files are created, the virt-install process can be initiated. First copy the downloaded Cloud Image file and optionally adjust the virtual disk size. -[source,bash] ----- -[…]# cp /var/lib/libvirt/boot/Fedora-Cloud-Base-33-1.2.x86_64.qcow2 \ - /var/lib/libvirt/images/VM_NAME.qcow2 -[…]# qemu-img resize /var/lib/libvirt/images/VM_NAME.qcow2 +10G -[…]# qemu-img info /var/lib/libvirt/images/VM_NAME.qcow2 ----- -Execute virt-install and adjust the values of CPU, memory, external network interface etc. to the requirements! -[source,bash] ----- -[…]# virt-install --name VM_NAME \ - --memory 3074 --cpu host --vcpus 3 --graphics none \ - --os-type linux --os-variant fedora33 \ - --import \ - --graphics none \ - --disk /var/lib/libvirt/images/VM_NAME.qcow2,format=qcow2,bus=virtio \ - --network type=direct,source=enpXsY,source_mode=bridge,model=virtio \ - --network bridge=virbr0,model=virtio \ - --cloud-init meta-data=/var/lib/libvirt/boot/cloud-init/meta-data,user-data=/var/lib/libvirt/boot/cloud-init/user-data ----- -It takes some time, be patient. After a while a login prompt is shown. Don’t try to login immediately. After some seconds the initialization process will continue. Finally, you see a message like -[source,text] ----- -... -[ OK ] Finished Network Manager Wait Online. -[ OK ] Reached target Network is Online. - -Fedora 34 (Cloud Edition) -Kernel 5.11.12-300.fc34.x86_64 on an x86_64 (ttyS0) - -eth0: 192.168.yyy.zzz 2003:ca:xxxx:yyyy:zzzz:aa:bb:cc -eth1: 192.168.mmm.nnn -my-vm login: ----- - -If the network environment issues IP addresses based on MAC addresses via DHCP, add to the the first network configuration the MAC address: -[source,text] ----- ---network type=direct,source=enpXsY,source_mode=bridge,mac=52:54:00:aa:bb:cc,model=virtio ----- - -Remember, that the first 3 pairs in the MAC address must be the sequence '52:54:00' for KVM virtual machines. - -==== Check installation - -Finally, login and check the installation. All interfaces should be up and running. -[source,bash] ----- -[…]# ip a ----- - -Name resolution should work without further configuration -[source,bash] ----- -[…]# resolvectl domain - Global: - Link 2 (eth0): ~. - Link 3 (eth1): .lan -[…]# resolvectl dns - Global: - Link 2 (eth0): 213.133.98.98 2a01:4f8:0:1::add:1010 - Link 3 (eth1): 192.168.122.1 ----- - -You should be able to connect to internal and external destinations -[source,bash] ----- -[…]# ping .lan -[…]# ping -[…]# ping6 ----- - -Everything should work flawlessly. - -Back on host finally enable autostart of the VM -[source,bash] ----- -[…]# virsh autostart VM_NAME - ----- -Everything done now. - -=== Conclusion - -Configuring the cloud-init process by virt-install version 3 is highly efficient and flexible. You may create a dedicated set of files for each VM or you may keep one set of generic files and adjust them by commenting in and out as required. A combination of both can be use. You can quickly and easily change configuration settings to test suitability for your purposes. - -Thus, a -configuration process is initiated quite comfortably that would otherwise be quite time-consuming. It is this performance that makes the use of cloud images so attractive. - -In summary, the use of Cloud Base Images comes with some inconveniences and suffers from shortcomings in documentation, overall the combination of Cloud Base Images and virt-install version 3 is a great combination for creating virtual machines for Fedora Server Edition. \ No newline at end of file diff --git a/docs/modules/ROOT/pages/virtualization-vminstall.adoc b/docs/modules/ROOT/pages/virtualization-vminstall.adoc deleted file mode 100644 index a8b62c0..0000000 --- a/docs/modules/ROOT/pages/virtualization-vminstall.adoc +++ /dev/null @@ -1,16 +0,0 @@ -= Installing Virtual Machines using Cockpit -Peter Boy; Jan Kuparinen -:page-authors: {author}, {author_2} - -[sidebar] -**** -Author: Peter Boy (pboy) | Creation Date: N/A | Last update: N/A | Related Fedora Version(s): 33 -**** -[NOTE] -==== -Work in progress. Coming soon -==== - - - -