cvm-image-rewriter: refine the cvm-image-rewriter

- Refine the cvm-image-rewriter
- Add readme for each plugin
- Update the serial number of plugin

Signed-off-by: Yanbo0101 <yanbo.xu@intel.com>

tools/cvm-image-rewriter/README.md

@@ -37,7 +37,7 @@ framework, and the whole flow was divided into three stages:
 
 ### 2.1 Existing Plugins
 
-There are following customization plugins in Pre-Stage providing customization to base image.
+There are following customization plugins in Plugins providing customization to base image.
 
 | Name | Descriptions | Required for CCNP deployment |
 | ---- | ------------ | ------------ |
@@ -46,28 +46,29 @@ There are following customization plugins in Pre-Stage providing customization t
 | 03-netplan | Customize the netplan.yaml | N |
 | 04-user-authkey | Add auth key for user login instead of password | N |
 | 05-readonly-data | Fix some file permission to ready-only | N |
-| 07-install-mvp-guest | Install MVP TDX guest kernel | Y |
-| 08-device-permission | Fix the permission for device node | Y |
-| 09-ccnp-uds-directory-permission | Fix the permission for CCNP UDS directory | Y |
+| 06-install-tdx-guest-kernel | Install MVP TDX guest kernel | Y |
+| 07-device-permission | Fix the permission for device node | Y |
+| 08-ccnp-uds-directory-permission | Fix the permission for CCNP UDS directory | Y |
 | 60-initrd-update | Update the initrd image | N |
+| 97-sample | plugin customization example | N |
 | 98-ima-enable-simple | Enable IMA (Integrity Measurement Architecture) feature | N |
 
 ### 2.2 Design a new plugin
 
-A plugin is put into the directory of [`pre-stage`](/tools/cvm-image-rewriter/pre-stage/),
+A plugin is put into the directory of [`plugins`](/tools/cvm-image-rewriter/plugins/),
 with the number as directory name's prefix. So the execution of plugin will be
-dispatched according to number sequence for example `99-test` is the final one.
+dispatched according to number sequence for example `99-byebye` is the final one.
 
 A plugin includes several customization approaches:
 
 1. File override: all files under `<plugin directory>/files` will be copied the
 corresponding directory in target guest image.
-2. Pre-stage execution on the host: the `<plugin directory>/host_run.sh` will be
+2. Pre-stage execution on the host: the `<plugin directory>/pre-stage/host_run.sh` will be
 executed before cloud-init stage
 3. cloud-init customization: please put the config yaml into `<plugin directory>/cloud-init/cloud-config`,
 and put the scripts to `<plugin directory>/cloud-init/x-shellscript`
 
-Please refer [the sample plugin](/tools/cvm-image-rewriter/pre-stage/99-test/).
+Please refer [the sample plugin](/tools/cvm-image-rewriter/plugins/97-sample/).
 
 ## 3. How to Run the tool
 
@@ -76,7 +77,7 @@ Please refer [the sample plugin](/tools/cvm-image-rewriter/pre-stage/99-test/).
 1. This tool has been tested on `Ubuntu 22.04` and `Debian 10`. It is recommend to use
 `Ubuntu 22.04`.
 
-2. This tool can run on bare metal or virtual machine (with nest VM like `Intel VT-x`, detailed in [Section 3.4](#3.4-Run-in-Nested-VM-(Optional)))
+2. This tool can run on bare metal or within a virtual machine using nesting as detailed in [Section 3.4](#3.4-Run-in-Nested-VM-(Optional))
 
 3. Please install following packages on Ubuntu/Debian:
 
@@ -136,19 +137,22 @@ Before running the tool, please choose the plugins that are needed.You can skip
 For example:
 
     ```
-    touch pre-stage/01-resize-image/NOT_RUN
+    touch plugins/01-resize-image/NOT_RUN
     ```
 
 If the guest image is used for CCNP deployment, it's recommended to run below plugin combination according to different initial guest image type.
 Others are not required by CCNP and can be skipped.
-|  Base image | 01  | 02  | 03  | 04  | 05 | 07 | 08 | 09 | 60 | 98 |
+|  Base image | 01  | 02  | 03  | 04  | 05 | 06 | 07 | 08 | 60 | 98 |
 |---|---|---|---|---|---|---|---|---|---|---|
-|  Ubuntu base image | | | | | Y| | Y| Y| | |
+|  Ubuntu base image | | | | | | Y| Y| Y| | |
 | TD enlightened image | | | | | | | Y| Y| | |
 
 **NOTE:**
-  - TD enlightened image means the image already has TDX kernel. If not, plugin 05 is needed to install TDX kernel.
-  - Plugin 08 and 09 prepares device permission for CCNP deployment.
+  - All plugins need to be executed in numerical order.
+  - TD enlightened image means the image already has TDX kernel. If not, plugin 06 is needed to install TDX kernel.
+  - Plugin 7 and Plugin 8 need to be executed before deploying CCNP to provide device permissions for CCNP.
+  - Plugin 60 requires copying or generating all files to the root directory first. When users customize plugins, please ensure that the plugin number with this requirement is placed before 60.
+  - Plugin 98 needs to be executed after all other plugins have completed. The number of the user-customized plugin must be before 98.
   - Other plugins are optional for CCNP deployment. 
 
 The tool supports parameters as below.
@@ -163,7 +167,7 @@ Optional
   -s <connection socket>    Default is connection URI is qemu:///system,
                             if install libvirt, you can specify to "/var/run/libvirt/libvirt-sock"
                             then the corresponding URI is "qemu+unix:///system?socket=/var/run/libvirt/libvirt-sock"
-  -n                        Silence running for virt-install, no output
+  -n                        Silent running for virt-install with no output
   -h                        Show usage
 ```
 

tools/cvm-image-rewriter/plugins/01-resize-image/README.md

@@ -0,0 +1,9 @@
+# Resize the image
+
+This plugin is used to extend the guest image size to given value from the
+environment variable `${GUEST_SIZE}`.
+
+If `${GUEST_SIZE}` is not specified like below, then this plugin will be skipped.
+```
+export GUEST_SIZE=50G
+```

tools/cvm-image-rewriter/pre-stage/01-resize-image/host_run.sh → tools/cvm-image-rewriter/plugins/01-resize-image/pre-stage/host_run.sh

@@ -1,9 +1,10 @@
 #!/bin/bash
 
 CURR_DIR=$(dirname "$(readlink -f "$0")")
-
+TOP_DIR="${CURR_DIR}/../../../"
+SCRIPTS_DIR="${TOP_DIR}/scripts"
 # shellcheck disable=SC1091
-source "${CURR_DIR}/../../scripts/common.sh"
+source "${SCRIPTS_DIR}/common.sh"
 
 info "Guest Image is at ${GUEST_IMG}..."
 

tools/cvm-image-rewriter/plugins/02-motd-welcome/README.md

@@ -0,0 +1,3 @@
+# Motd welcome
+
+This plugin is used to set the information in `/etc/motd`, which will be displayed after successful login. Users can customize the welcome information by updating the content of `files/etc/motd`.

tools/cvm-image-rewriter/plugins/03-netplan/README.md

@@ -0,0 +1,3 @@
+# Netplan
+
+This plugin is used to add network configuration file `netplan.yaml` in the `/etc/netplan/` directory, which will configure the network for the guest image. Users can customize netplan.yaml by updating the contents of `files/etc/netplan/netplan.yaml`

tools/cvm-image-rewriter/plugins/04-user-authkey/README.md

@@ -0,0 +1,14 @@
+# User authkey
+
+This plugin is used to set the SSH login user and public key using environment variables `${CVM_USER}` and `${CVM_AUTH_KEY}`.
+
+The default value of `${CVM_USER}` is "cvm", and users can customize it as shown below.
+```
+export CVM_USER=<user>
+```
+
+The `${CVM_AUTH_KEY}` has no default value, users need to set it themselves. If `${CVM_AUTH_KEY}` is not specified like below, this plugin will be skipped.
+
+```
+export CVM_AUTH_KEY=<ssh public key>
+```

tools/cvm-image-rewriter/pre-stage/05-readonly-data/clean_up.sh → tools/cvm-image-rewriter/plugins/04-user-authkey/post-stage/clean_up.sh

@@ -1,7 +1,7 @@
 #!/bin/bash
 
 DIR=$(dirname "$(readlink -f "$0")")
-CLD_DIR="$DIR/cloud-init"
+CLD_DIR="$DIR/../cloud-init"
 
 if [[ -d "$CLD_DIR" ]]; then
     rm -rf "$CLD_DIR"

tools/cvm-image-rewriter/pre-stage/04-user-authkey/host_run.sh → tools/cvm-image-rewriter/plugins/04-user-authkey/pre-stage/host_run.sh

@@ -4,21 +4,21 @@
 pushd "$(dirname "$(readlink -f "$0")")" || exit 0
 
 # shellcheck disable=SC1091
-source ../../scripts/common.sh
+source ../../../scripts/common.sh
 
 # Check CVM_USER, CVM_AUTH_KEY
 CVM_USER="${CVM_USER:-cvm}"
 info "Config user: $CVM_USER"
 
 if [[ -z "$CVM_AUTH_KEY" ]]; then
-    warn "CVM_AUTH_KEY is not set, skip"
+    warn "SKIP: CVM_AUTH_KEY is not defined via environment variable 'CVM_AUTH_KEY'"
     exit 0
 fi
 info "ssh pubkey: $CVM_AUTH_KEY"
 
 # Generate cloud-config
-mkdir -p cloud-init/cloud-config/
-cat > cloud-init/cloud-config/04-user-authkey.yaml << EOL
+mkdir -p ../cloud-init/cloud-config/
+cat > ../cloud-init/cloud-config/04-user-authkey.yaml << EOL
 #cloud-config
 merge_how:
   - name: list

tools/cvm-image-rewriter/plugins/05-readonly-data/README.md

@@ -0,0 +1,3 @@
+# Readonly data
+
+This plugin is used to fix some file permissions to read-only. Users can specify the names of files and directories that need to be fixed in the `pre-stage/file_list`.

tools/cvm-image-rewriter/plugins/05-readonly-data/post-stage/clean_up.sh

@@ -0,0 +1,8 @@
+#!/bin/bash
+
+DIR=$(dirname "$(readlink -f "$0")")
+CLD_DIR="$DIR/../cloud-init"
+
+if [[ -d "$CLD_DIR" ]]; then
+    rm -rf "$CLD_DIR"
+fi

tools/cvm-image-rewriter/pre-stage/05-readonly-data/host_run.sh → tools/cvm-image-rewriter/plugins/05-readonly-data/pre-stage/host_run.sh

@@ -3,7 +3,7 @@
 DIR=$(dirname "$(readlink -f "$0")")
 FILE_LIST="$DIR/file_list"
 CLD_SH_READONLY_FILE="01-file-readonly.sh"
-CLD_SH="$DIR/cloud-init/x-shellscript/$CLD_SH_READONLY_FILE"
+CLD_SH="$DIR/../cloud-init/x-shellscript/$CLD_SH_READONLY_FILE"
 CLD_SH_TEMPLATE=""
 injects=""
 
@@ -25,6 +25,6 @@ while IFS= read -r line || [ -n "$line" ]; do
     fi
 done <"$FILE_LIST"
 
-mkdir -p "$DIR/cloud-init/x-shellscript"
+mkdir -p "$DIR/../cloud-init/x-shellscript"
 # shellcheck disable=SC2001
 echo "$CLD_SH_TEMPLATE" | sed -e "s@PLACEHOLDER@$injects@g" > "$CLD_SH"

tools/cvm-image-rewriter/plugins/06-install-tdx-guest-kernel/README.md

@@ -0,0 +1,22 @@
+# Install TDX guest kernel
+
+This plugin is used to install TDX guest kernel from a given local repository.
+
+# Prerequisite
+
+Prepare the local repository and confirm that there are Debian packages related to the TDX kernel in the `/jammy/amd64/` directory of this repository. You can choose to place this local repository in the `pre-stage/artifacts/` directory.
+```
+mkdir -p ./pre-stage/artifacts
+mv <your guest repo> ./pre-stage/artifacts/
+```
+
+Set `${CVM_TDX_GUEST_REPO}` to the repository absolute path, or this plugin will be skipped. 
+```
+export CVM_TDX_GUEST_REPO=$(pwd)/pre-stage/artifacts/<your guest repo>
+
+# Or
+export CVM_TDX_GUEST_REPO=<your local guest repo>
+```
+
+
+_NOTE: IF the original image is smaller than 1.5G, please also set the environment variable GUEST\_SIZE larger ._

tools/cvm-image-rewriter/plugins/06-install-tdx-guest-kernel/post-stage/clean_up.sh

@@ -0,0 +1,8 @@
+#!/bin/bash
+
+DIR=$(dirname "$(readlink -f "$0")")
+CLD_DIR="$DIR/../cloud-init"
+
+if [[ -d "$CLD_DIR" ]]; then
+    rm -rf "$CLD_DIR"
+fi

tools/cvm-image-rewriter/plugins/06-install-tdx-guest-kernel/pre-stage/host_run.sh

@@ -0,0 +1,48 @@
+#!/bin/bash
+
+CURR_DIR=$(dirname "$(readlink -f "$0")")
+TOP_DIR="${CURR_DIR}/../../../"
+SCRIPTS_DIR="${TOP_DIR}/scripts"
+# shellcheck disable=SC1091
+source "${SCRIPTS_DIR}/common.sh"
+ARTIFACTS_GUEST=/srv
+
+# check environment variable 'CVM_TDX_GUEST_REPO'
+if [[ -z "$CVM_TDX_GUEST_REPO" ]]; then
+    warn "SKIP: TDX guest repo is not defined via environment variable 'CVM_TDX_GUEST_REPO' "
+    exit 0
+fi
+
+info "TDX Guest Repo is at ${CVM_TDX_GUEST_REPO}..."
+
+# check if the repo exists
+if [[ ! -d "$CVM_TDX_GUEST_REPO" ]]; then
+    warn "SKIP: TDX guest local repo CVM_TDX_GUEST_REPO does not exist."
+    exit 0
+fi
+
+# Check if it is a valid TDX repo
+if ! compgen -G "$CVM_TDX_GUEST_REPO/jammy/amd64/linux-image-*mvp*.deb"; then
+    warn "SKIP: $CVM_TDX_GUEST_REPO is invalid."
+    exit 0
+fi
+
+info "TDX guest local repo $CVM_TDX_GUEST_REPO check passed"
+
+# Copy TDX local repo from host to guest
+virt-copy-in -a "${GUEST_IMG}" "$CVM_TDX_GUEST_REPO" "$ARTIFACTS_GUEST"
+ok "TDX guest local repo $CVM_TDX_GUEST_REPO copied to guest $ARTIFACTS_GUEST"
+
+# Generate cloud-config
+mkdir -p "${CURR_DIR}/../cloud-init/x-shellscript/"
+cat > "${CURR_DIR}/../cloud-init/x-shellscript/07-install-tdx-guest-kernel.sh" << EOL
+#!/bin/bash
+
+PACKAGE_DIR=""$ARTIFACTS_GUEST"/$(basename "$CVM_TDX_GUEST_REPO")/jammy/"
+pushd \$PACKAGE_DIR || exit 0
+apt install ./amd64/linux-image-unsigned-*.deb ./amd64/linux-modules-*.deb \
+        ./amd64/linux-headers-*.deb ./all/linux-headers-*.deb --allow-downgrades -y
+popd || exit 0
+EOL
+
+ok "Cloud config cloud-init/x-shellscript/07-install-tdx-guest-kernel.sh generated"

tools/cvm-image-rewriter/plugins/07-device-permission/README.md

@@ -0,0 +1,3 @@
+# Device permission
+
+This plugin is used to setup udev rules for CCNP device plugin. Users do not need to customize.

tools/cvm-image-rewriter/plugins/08-ccnp-uds-directory-permission/README.md

@@ -0,0 +1,3 @@
+# CCNP UDS directory permission
+
+This plugin is used to prepare shared Unix domain socket directories for CCNP. Users do not need to customize.

tools/cvm-image-rewriter/plugins/60-initrd-update/README.md

@@ -0,0 +1,3 @@
+# Initrd update
+
+This plugins is used to update the initrd image. Users place executable files in the `files/` directory, and the plugin will copy these executable files to the initramfs.

tools/cvm-image-rewriter/pre-stage/60-initrd-update/clean_up.sh → tools/cvm-image-rewriter/plugins/60-initrd-update/post-stage/clean_up.sh

@@ -1,7 +1,7 @@
 #!/bin/bash
 
 DIR=$(dirname "$(readlink -f "$0")")
-ETC_DIR="$DIR/files/etc"
+ETC_DIR="$DIR/../files/etc"
 
 if [[ -d "$ETC_DIR" ]]; then
     rm -rf "$ETC_DIR"

tools/cvm-image-rewriter/pre-stage/60-initrd-update/host_run.sh → tools/cvm-image-rewriter/plugins/60-initrd-update/pre-stage/host_run.sh

@@ -3,15 +3,15 @@
 DIR=$(dirname "$(readlink -f "$0")")
 TEMPLATE="#!/bin/sh\n\n. /usr/share/initramfs-tools/hook-functions\n"
 
-HOOKS_DIR="$DIR/files/etc/initramfs-tools/hooks"
+HOOKS_DIR="$DIR/../files/etc/initramfs-tools/hooks"
 SCRIPT_NAME=initrd-custom-update.sh
 SCRIPT_PATH=$HOOKS_DIR/$SCRIPT_NAME
 
 mkdir -p "$HOOKS_DIR"
 echo -e "$TEMPLATE" > "$SCRIPT_PATH"
 chmod a+x "$SCRIPT_PATH"
 
-mapfile -t files < <(find "$DIR/files" -type f)
+mapfile -t files < <(find "$DIR/../files" -type f)
 for f in "${files[@]}"
 do
     if [[ $f == *$SCRIPT_NAME ]]; then

tools/cvm-image-rewriter/plugins/97-sample/README.md

@@ -0,0 +1,16 @@
+# Sample
+
+This is a sample plugin to show the structure of the plugin and how to customize it.
+
+Example Output:
+```
+# output of the cloud-init
+=========== example for customized x-shellscript ===========
+
+#  output of the pre-stage
+pre-stage host_run "haha"
+
+# output of the post-stage
+post-stage host_run "haha"
+post-stage clean_up "haha"
+```

tools/cvm-image-rewriter/plugins/97-sample/post-stage/clean_up.sh

@@ -0,0 +1,3 @@
+#!/bin/bash
+
+echo "post-stage clean_up \"haha\""

tools/cvm-image-rewriter/plugins/97-sample/post-stage/host_run.sh

@@ -0,0 +1,3 @@
+#!/bin/bash
+
+echo "post-stage host_run \"haha\""

tools/cvm-image-rewriter/plugins/97-sample/pre-stage/host_run.sh

@@ -0,0 +1,3 @@
+#!/bin/bash
+
+echo "pre-stage host_run \"haha\" "

tools/cvm-image-rewriter/pre-stage/98-ima-enable-simple/clean_up.sh → tools/cvm-image-rewriter/plugins/98-ima-enable-simple/post-stage/clean_up.sh

@@ -2,7 +2,7 @@
 
 DIR=$(dirname "$(readlink -f "$0")")
 CLD_SH_REGISTER_FILE_HASH="01-ima-register-file-hash.sh"
-CLD_SH="$DIR/cloud-init/x-shellscript/$CLD_SH_REGISTER_FILE_HASH"
+CLD_SH="$DIR/../cloud-init/x-shellscript/$CLD_SH_REGISTER_FILE_HASH"
 
 if [[ -f "$CLD_SH" ]]; then
     rm "$CLD_SH"

tools/cvm-image-rewriter/pre-stage/98-ima-enable-simple/host_run.sh → tools/cvm-image-rewriter/plugins/98-ima-enable-simple/pre-stage/host_run.sh

@@ -3,7 +3,7 @@
 DIR=$(dirname "$(readlink -f "$0")")
 FILE_LIST="$DIR/file_list"
 CLD_SH_REGISTER_FILE_HASH="01-ima-register-file-hash.sh"
-CLD_SH="$DIR/cloud-init/x-shellscript/$CLD_SH_REGISTER_FILE_HASH"
+CLD_SH="$DIR/../cloud-init/x-shellscript/$CLD_SH_REGISTER_FILE_HASH"
 CLD_SH_TEMPLATE=""
 injects=""
 

tools/cvm-image-rewriter/post-stage/99-byebye/host_run.sh → tools/cvm-image-rewriter/plugins/99-byebye/post-stage/host_run.sh

@@ -1,7 +1,7 @@
 #!/bin/bash
 
 CURR_DIR=$(dirname "$(readlink -f "$0")")
-TOP_DIR="${CURR_DIR}/../../"
+TOP_DIR="${CURR_DIR}/../../../"
 SCRIPTS_DIR="${TOP_DIR}/scripts"
 
 # shellcheck disable=SC1091