Merge branch 'apache:main' into main

Author: sbrueseke

source/_static/images/B&R-Backup-Respository.png

@@ -0,0 +1,30 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+   or more contributor license agreements.  See the NOTICE file
+   distributed with this work for additional information#
+   regarding copyright ownership.  The ASF licenses this file
+   to you under the Apache License, Version 2.0 (the
+   "License"); you may not use this file except in compliance
+   with the License.  You may obtain a copy of the License at
+   http://www.apache.org/licenses/LICENSE-2.0
+   Unless required by applicable law or agreed to in writing,
+   software distributed under the License is distributed on an
+   "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+   KIND, either express or implied.  See the License for the
+   specific language governing permissions and limitations
+   under the License.
+
+
+Hosts/Cluster Arch Types Allocation
+===================================
+
+Since CloudStack 4.20.0, it is possible to add AMD 64 bits and ARM 64 bits clusters (and hosts). A single zone can contain clusters (and hosts) of different arch types (multi-arch zones). 
+
+When a multi-arch zone is selected for VM deployment, CloudStack allows the users to filter the templates/ISOs by their arch type.
+
+|deploy-vm-arch-types.png|
+
+Once a template/ISO is selected, only the clusters (and hosts) matching the arch type will be considered for the VM allocation
+
+.. |deploy-vm-arch-types.png| image:: /_static/images/deploy-vm-arch-types.png
+   :alt: Filtering templates and ISOs by arch types
+

source/_static/images/deploy-vm-arch-types.png

@@ -139,6 +139,7 @@ Managing VM and Volume Allocation
    :maxdepth: 4
 
    host_and_storage_tags
+   arch_types
 
 Managing Networks and Traffic
 -----------------------------

source/adminguide/arch_types.rst

@@ -517,6 +517,52 @@ rules.
    the global configuration.
 
 
+Managing log files
+------------------
+
+The log files are located in `/var/log/cloudstack`. This directory has the
+following subdirectories:
+
+- `management` for the Management Server
+- `usage` for the Usage Server
+- `agent` for the Agent for KVM hosts
+
+CloudStack uses log4j2 to manage log files. The log4j2 configuration file
+is located in the corresponding subdirectories in the `/etc/cloudstack/` 
+directory and is named `log4j-cloud.xml`.
+
+By default, cloudstack uses `TimeBasedTriggeringPolicy` which rolls over
+the log file every day and are kept indefinitely. The log files are 
+compressed and archived in the same directory.
+
+Over time, the logs can fill up the entire disk space. To avoid this, you can 
+update the log4j-cloud.xml file to change the log file rollover and retention 
+policy. You can change the rollover policy to `SizeBasedTriggeringPolicy`
+and set the maximum size of the log file. You can also set the maximum number
+of archived log files to keep.
+
+For example, to change the rollover policy for `management-server.log` to 
+`SizeBasedTriggeringPolicy` and set the maximum size of the log file to 
+100MB and keep the maximum of 15 archived log files, you can update the 
+`log4j-cloud.xml` file as follows:
+
+.. code-block:: diff
+
+   -      <RollingFile name="FILE" append="true" fileName="/var/log/cloudstack/management/management-server.log" filePattern="/var/log/cloudstack/management/management-server.log.%d{yyyy-MM-dd}.gz">
+   +      <RollingFile name="FILE" append="true" fileName="/var/log/cloudstack/management/management-server.log" filePattern="/var/log/cloudstack/management/management-server.log.%i.gz">
+            <ThresholdFilter level="TRACE" onMatch="ACCEPT" onMismatch="DENY"/>
+   +          <DefaultRolloverStrategy max="15"/>
+            <Policies>
+   -            <TimeBasedTriggeringPolicy/>
+   +            <SizeBasedTriggeringPolicy size="100MB"/>
+            </Policies>
+            <PatternLayout pattern="%d{DEFAULT} %-5p [%c{1.}] (%t:%x) %m%ex%n"/>
+         </RollingFile>
+
+
+You can also checkout some configuration recipes from the log4j2 documentation
+`here <https://logging.apache.org/log4j/2.x/manual/appenders/rolling-file.html#recipes>`_.
+
 Stopping and Restarting the Management Server
 ---------------------------------------------------
 

source/adminguide/index.rst

@@ -56,6 +56,36 @@ admins can create new backup offerings by selecting the zone and the backup
 repository. These backup offerings are then assigned and used with KVM instances
 to perform support B&R actions and operations.
 
+Using the NAS Backup and Recovery Plugin
+----------------------------------------
+To use the NAS Backup and Recovery Plugin, the Backup and Recovery framework needs to be enabled first. Then the backup plugin 'nas' needs to be enabled on either the global or zone settings. 
+
+================================= ========================
+Configuration                     Value
+================================= ========================
+backup.framework.enabled          true
+backup.framework.provider.plugin  nas
+================================= ========================
+
+Once the above two configurations are set, restart the cloudstack-management service. Once the service is restarted we can add the backup repository for the 'nas' Backup and Recovery plugin.
+Navigate to the configuration -> Backup Repository. Click on 'Add Backup Repository' and fill the form. 
+
+=================== ========================
+Field               Value
+=================== ========================
+Name                A suitable name to represent the Backup Repository
+Address             URL, in case of NFS <server IP>:/path
+Type                NFS ( only NFS type in 4.20)
+label.mountopts     Any mount point options to be passed while mouting this storage on the hypervisor. 
+Zone                The zone in CloudStack with which this Backup Repository must be associated.
+=================== ========================
+
+.. image:: /_static/images/B&R-Backup-Respository.png
+   :align: center
+   :alt: NAS Backup repository
+
+Once the Backup Repository is created, we need to add a Backup Offering, in this plugin the Backup offering is a placeholder to associate an instance to a Backup Repository. While creating the Backup Offering, select the desired Backup Repository. Associate the Backup Offering on an instance to create an Adhoc or scheduled backup. 
+
 Support Information and Limitation
 ----------------------------------
 

source/adminguide/management.rst

@@ -281,6 +281,8 @@ To upload a Template:
    -  **Hypervisor**: The supported hypervisors are listed. Select the
       desired one.
 
+   -  **Arch**: The supported arch types are listed. Select the desired one.
+
    -  **Format**. The format of the Template upload file, such as VHD or
       OVA.
 
@@ -328,7 +330,7 @@ Example GUI dialog of uploading Template/ISO from local (browser) is given below
 
 |upload-iso-from-local.png|
 
-Note that uploading multi-disk Templates is also supported.
+Note that uploading multi-disk Templates is also supported as well as selecting the template/ISO arch type.
 
 Sharing Templates and ISOs with other Accounts/projects
 -------------------------------------------------------
@@ -545,6 +547,8 @@ part of a Template.
       prominent for Users to select. The ISO will appear in the Featured
       ISOs list. Only an administrator can make an ISO Featured.
 
+   -  **Arch**: The supported arch types are listed. Select the desired one.
+
 #. Click OK.
 
    The Management Server will download the ISO. Depending on the size of

source/adminguide/nas_plugin.rst

@@ -294,6 +294,10 @@ For the management server role we create a main.yml task like this:
 
 Save this as `/etc/ansible/roles/cloudstack-management/tasks/main.yml`
 
+.. note:: In a production environment, selinux should be set to enforcing
+   and the necessary selinux policies are created to allow the
+   services to run.
+
 Now we have some new elements to deal with. The Ansible Template module
 uses Jinja2 based templating.  As we’re doing a simplified example here,
 the Jinja Template for the cloudstack.repo won’t have any variables in

source/adminguide/templates.rst

@@ -871,6 +871,9 @@ You need to tell CloudStack about the hosts that it will manage. Hosts
 exist inside clusters, so before you begin adding hosts to the cloud,
 you must add at least one cluster.
 
+.. note::
+      Since CloudStack 4.20.0, it is possible to specify the hosts arch type which must be homogeneous within the cluster. AMD 64 bits (x86_64) and ARM 64 bits (aarch64) arch types are supported. The pre-existing clusters are set to arch type AMD 64 bits as well as new clusters in which the arch type is not specified.
+
 
 Add Cluster: KVM or XenServer
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -889,6 +892,8 @@ hosts and logged in to the CloudStack UI.
 
 #. Choose the hypervisor type for this cluster.
 
+#. Choose the arch type of the hosts within the cluster.
+
 #. Choose the pod in which you want to create the cluster.
 
 #. Enter a name for the cluster. This can be text of your choosing and
@@ -1008,7 +1013,7 @@ Requirements for XenServer and KVM Hosts
 
 Configuration requirements:
 
--  Each cluster must contain only hosts with the identical hypervisor.
+-  Each cluster must contain only hosts with the identical hypervisor and arch type.
 
 -  For XenServer, do not put more than 8 hosts in a cluster.
 
@@ -1017,6 +1022,8 @@ Configuration requirements:
 For hardware requirements, see the installation section for your
 hypervisor in the CloudStack Installation Guide.
 
+.. note::
+   Since CloudStack 4.20.0, the host arch type is auto detected when adding the host into CloudStack and it must match the cluster arch type for the operation to succeed.
 
 XenServer Host Additional Requirements
 ''''''''''''''''''''''''''''''''''''''

source/developersguide/ansible.rst

@@ -472,6 +472,13 @@ cloudstack-agent and should already be installed.
 
       #LIBVIRTD_ARGS="--listen"
 
+   Configure libvirt to connect to libvirtd and not to per-driver daemons, especially important on newer distros such as EL9 and Ubuntu 24.04. 
+   Edit ``/etc/libvirt/libvirt.conf`` and add the following:
+
+   .. parsed-literal::
+      remote_mode="legacy"
+
+
 #. Restart libvirt
 
    In RHEL or CentOS or SUSE or Ubuntu:
@@ -529,6 +536,10 @@ ensure the Agent has all the required permissions.
 
          $ setenforce permissive
 
+.. note:: In a production environment, selinux should be set to enforcing
+   and the necessary selinux policies are created to allow the
+   services to run.
+
 #. Configure Apparmor (Ubuntu)