diff --git a/.idea/docs.iml b/.idea/docs.iml deleted file mode 100644 index d0876a78d06ac03b5d78c8dcdb95570281c6f1d6..0000000000000000000000000000000000000000 --- a/.idea/docs.iml +++ /dev/null @@ -1,8 +0,0 @@ - - - - - - - - \ No newline at end of file diff --git a/.idea/inspectionProfiles/profiles_settings.xml b/.idea/inspectionProfiles/profiles_settings.xml deleted file mode 100644 index 105ce2da2d6447d11dfe32bfb846c3d5b199fc99..0000000000000000000000000000000000000000 --- a/.idea/inspectionProfiles/profiles_settings.xml +++ /dev/null @@ -1,6 +0,0 @@ - - - - \ No newline at end of file diff --git a/.idea/misc.xml b/.idea/misc.xml deleted file mode 100644 index 65531ca992813bbfedbe43dfae5a5f4337168ed8..0000000000000000000000000000000000000000 --- a/.idea/misc.xml +++ /dev/null @@ -1,4 +0,0 @@ - - - - \ No newline at end of file diff --git a/.idea/modules.xml b/.idea/modules.xml deleted file mode 100644 index 6049cfe013e0d2ef3f5f29c1b34b880e9d498ef0..0000000000000000000000000000000000000000 --- a/.idea/modules.xml +++ /dev/null @@ -1,8 +0,0 @@ - - - - - - - - \ No newline at end of file diff --git a/.idea/vcs.xml b/.idea/vcs.xml deleted file mode 100644 index 94a25f7f4cb416c083d265558da75d457237d671..0000000000000000000000000000000000000000 --- a/.idea/vcs.xml +++ /dev/null @@ -1,6 +0,0 @@ - - - - - - \ No newline at end of file diff --git a/DEVELOPER_DOCS/maintainers.yaml b/DEVELOPER_DOCS/maintainers.yaml deleted file mode 100644 index 539cce605c54a907126ba9df62c8ef9ce840ad50..0000000000000000000000000000000000000000 --- a/DEVELOPER_DOCS/maintainers.yaml +++ /dev/null @@ -1,24 +0,0 @@ -# 指定所有 maintainers -maintainers: - - default_group: &default_group - - openanolis_id: xx - gitee_id: xxxx - - network_group: &network_group - - openanolis_id: yankai - gitee_id: just-sososo - - openanolis_id: yankai - gitee_id: just-sososo - - io_group: &io_group - - openanolis_id: lisi - gitee_id: lisi - - openanolis_id: xxx - gitee_id: just-sososo - - other_group: &other_group - - openanolis_id: yankai - gitee_id: just-sososo -# 指定文档目录对应的用户组 -paths: - - /*: *default_group - - ./network/*: *network_group - - ./DEVELOPER_DOCS/*: *other_group - - path3: *other_group \ No newline at end of file diff --git a/DEVELOPER_DOCS/menu.yaml b/DEVELOPER_DOCS/menu.yaml deleted file mode 100644 index 74a2565ae121e50004e6df4f0caa724340318208..0000000000000000000000000000000000000000 --- a/DEVELOPER_DOCS/menu.yaml +++ /dev/null @@ -1,10 +0,0 @@ -DEVELOPER_DOCS: - menu: menu.yml - maintainers: maintainers.yml - 海光安全虚拟化技术CSV: - CSV机密容器-0.1.0: - 虚拟机中使用机密容器: ../海光安全虚拟化技术CSV/CSV机密容器-0.1.0/在kata CSV虚拟机中使用机密容器.md - 使用机密容器: ../海光安全虚拟化技术CSV/CSV机密容器-0.1.0/基于 runtime attestation 使用机密容器.md - CSV机密容器-0.5.0: - Anolis OS 8.6搭建并测试CSV机密容器: ../海光安全虚拟化技术CSV/CSV机密容器-0.5.0/Anolis OS 8.6搭建并测试CSV机密容器.md - CC场景如何下载需要auth的镜像: ../海光安全虚拟化技术CSV/CSV机密容器-0.5.0/CC场景如何下载需要auth的镜像.md \ No newline at end of file diff --git "a/DEVELOPER_DOCS/\346\265\267\345\205\211\345\256\211\345\205\250\350\231\232\346\213\237\345\214\226\346\212\200\346\234\257CSV/CSV\346\234\272\345\257\206\345\256\271\345\231\250-0.1.0/\345\234\250kata CSV\350\231\232\346\213\237\346\234\272\344\270\255\344\275\277\347\224\250\346\234\272\345\257\206\345\256\271\345\231\250.md" "b/DEVELOPER_DOCS/\346\265\267\345\205\211\345\256\211\345\205\250\350\231\232\346\213\237\345\214\226\346\212\200\346\234\257CSV/CSV\346\234\272\345\257\206\345\256\271\345\231\250-0.1.0/\345\234\250kata CSV\350\231\232\346\213\237\346\234\272\344\270\255\344\275\277\347\224\250\346\234\272\345\257\206\345\256\271\345\231\250.md" deleted file mode 100644 index 278d112abebf3ffe7963839b92088e61d2a2a05b..0000000000000000000000000000000000000000 --- "a/DEVELOPER_DOCS/\346\265\267\345\205\211\345\256\211\345\205\250\350\231\232\346\213\237\345\214\226\346\212\200\346\234\257CSV/CSV\346\234\272\345\257\206\345\256\271\345\231\250-0.1.0/\345\234\250kata CSV\350\231\232\346\213\237\346\234\272\344\270\255\344\275\277\347\224\250\346\234\272\345\257\206\345\256\271\345\231\250.md" +++ /dev/null @@ -1,19 +0,0 @@ -# 介绍 - -[Kata Containers ](https://github.com/confidential-containers/kata-containers-CCv0)是一个使用虚拟化来提供隔离层的开源安全容器项目。Kata支持机密计算硬件技术，通过利用可信执行环境(Trusted Execution Environments)来保护客户的高度敏感的工作负载，以防止不受信任的实体（例如：云服务商）访问租客的敏感数据。 - -在kata container中，您能够在在机密虚拟机中运行POD和容器，将主机/owner/管理员/CSP软件栈从kata 的TCB中移除，从而构建一个更强大的云原生多租户架构。具体做法是：在为每个租户使用的容器加密镜像远程Provisioning解密密钥前，先认证pod或容器是否已经运行在了经过认证的环境中。 - -海光CPU支持安全虚拟化技术CSV(China Secure Virtualization)，CSV的设计目标是通过CSV虚拟机提供可信执行环境，适用的场景包括云计算、机密计算等。海光2号支持CSV1技术，提供虚拟机内存加密能力，采用国密SM4算法，不同的CSV虚拟机使用不同的加密密钥，密钥由海光安全处理器管理，主机无法解密虚拟机的加密内存。 - -海光CSV加密虚拟机支持两种远程认证方式： - -- pre-attestation指需要在启动TEE之前能够执⾏行行attestation过程。在云上的CSV虚拟机启动的时候，对加载的ovmf，kernel，initrd，cmdline进行静态度量，生成measurement。线下的远程证明验证者对measurement进行验证，确保启动的CSV虚拟机是符合预期的。 -- runtime-attestation：在云上的CSV虚拟机运行的时候，产生带有硬件可执行环境的Quote的TLS证书。线下的远程证明验证者对TLS证书进行验证，确保CSV虚拟机运行在TEE中。 - -基于以上两种远程证明，我们提供了一下两篇最佳实践文档： - -1. 在kata CSV虚拟机中基于pre-attestation使用机密容器的指南，请参考[文档](https://openanolis.cn/sig/coco/doc/533510702679267994)。 -1. 在kata CSV虚拟机中基于runtime-attestation使用机密容器的指南，请参考[文档](https://openanolis.cn/sig/coco/doc/533511548301020780?)。 -修改文档内容 - diff --git "a/DEVELOPER_DOCS/\346\265\267\345\205\211\345\256\211\345\205\250\350\231\232\346\213\237\345\214\226\346\212\200\346\234\257CSV/CSV\346\234\272\345\257\206\345\256\271\345\231\250-0.1.0/\345\237\272\344\272\216 runtime attestation \344\275\277\347\224\250\346\234\272\345\257\206\345\256\271\345\231\250.md" "b/DEVELOPER_DOCS/\346\265\267\345\205\211\345\256\211\345\205\250\350\231\232\346\213\237\345\214\226\346\212\200\346\234\257CSV/CSV\346\234\272\345\257\206\345\256\271\345\231\250-0.1.0/\345\237\272\344\272\216 runtime attestation \344\275\277\347\224\250\346\234\272\345\257\206\345\256\271\345\231\250.md" deleted file mode 100644 index 51237303fa4c6e9c37616a05778dc1f51777fa6d..0000000000000000000000000000000000000000 --- "a/DEVELOPER_DOCS/\346\265\267\345\205\211\345\256\211\345\205\250\350\231\232\346\213\237\345\214\226\346\212\200\346\234\257CSV/CSV\346\234\272\345\257\206\345\256\271\345\231\250-0.1.0/\345\237\272\344\272\216 runtime attestation \344\275\277\347\224\250\346\234\272\345\257\206\345\256\271\345\231\250.md" +++ /dev/null @@ -1,650 +0,0 @@ -本文主要为您介绍如何在kata环境中基于海光安全加密虚拟化功能CSV(China Secure Virtualization)技术，通过runtime-attestaion 认证方式，启动一个租户的加密容器镜像。 - -# 前提条件 - -请使用安装Hygon CPU的硬件设备，硬件信息参考如下： - -- CPU型号：Hygon C86 7291 32-core Processor -- 固件版本：1600及以上 -- BIOS设置：开启SME - -BIOS选项SMEE用来控制是否打开内存加密功能，SMEE=Enable表示在BIOS中打开内存加密功能，SMEE=Disable表示在BIOS中关闭内存加密功能。 - -## 1. 安装Anolis 8.4 操作系统 - -请参考[Anolis 8.4 GA说明文档](https://mirrors.openanolis.cn/anolis/8.4/isos/GA/ReadMe.txt)安装anolis 8.4 GA。 - -## 2. 升级kernel到5.10 - -Anlois 8.4 的默认内核版本是4.19，5.10的内核上支持[CSV远程证明功能](https://gitee.com/anolis/cloud-kernel/pulls/14)。请升级kernel 到5.10版本。 - -1. 请参考以下命令，添加Anolis的Experimental repo，并将kernel升级至5.10。 -``` -yum-config-manager --add-repo https://mirrors.openanolis.cn/anolis/8/Experimental/x86_64/os/ && \ - yum update kernel -``` -2. 配置bootloader。 -``` -grubby --update-kernel=ALL --args="mem_encrypt=on kvm_amd.sev=1" -``` -3. 重启机器，请输入以下命令查看内核版本。 -```shell -uname -r -``` -预期输出： -```shell -5.10.134-12.an8.x86_64 -``` - -**注意！！** - -如果您使用的是Anolis 8.6 GA镜像，可能会碰到使能SEV之后，机器Hang住无法进入系统的情况。请参考以下步骤降级grub2-efi之后，可以正常启动这个特性 - -```sh -yum downgrade grub2-efi -``` - -## 3. 检查CSV使能状态 - -1. 在操作系统内执行： -``` -dmesg | grep -i sev -``` - -下图表示CSV已经使能。 - -![](https://oss.openanolis.cn/sig/jyxnkmbnxviifztgmeep) - -2. 检查kvm_amd和ccp模块是否成功安装。 -``` -lsmod | grep kvm -``` -下图表示成功安装。 - -![](https://oss.openanolis.cn/sig/ffhuletbduwrkhkkgaih) - -## 4. 使用hag检查固件版本信息 - -1. 安装hag - -```sh -yum-config-manager --add-repo https://mirrors.openanolis.org/inclavare-containers/anolis8.4 && \ - rpm --import https://mirrors.openanolis.org/inclavare-containers/anolis8.4/RPM-GPG-KEY-rpm-sign && \ - yum install -y hag -``` - -2. 通过hag获得平台状态 - -```sh -sudo hag --platform_status -api_major: 1 -api_minor: 3 -platform_state: CSV_STATE_WORKING -owner: PLATFORM_STATE_SELF_OWN -chip_secure: SECURE -fw_enc: ENCRYPTED -fw_sign: SIGNED -es: CSV ES -build id: 1644 -bootloader version: 0.0.0 -guest_count: 1 -supported csv guest:11 -platform_status command successful - -``` - -注意：固件 build id 要大于等于 1600 才可以支持远程证明。 - -## 5. 执行CSV 检查脚本，检查环境是否满足 (可选) -```sh -./check_csv_env.sh -``` - -脚本内容见附录 - -# 背景信息 - -![](https://oss.openanolis.cn/sig/mftnpcpuvawveyodvhtn) - -1. CSV VM启动； - -2. 下载加密镜像时才会通过attestation-agent将通过vm-attestation hypercall获取的包括attestation-report 、chip-id等内容的CSV VM evidence发送给verdictd server校验； - -3. 校验通过后virdictd才与attestation-agent建立基于rats-tls的可信硬件环境的安全通道、并将加密镜像的解密key通过该安全通道发送给attestation-agent； - -4. CSV VM利用步骤3获得的解密key解密镜像，运行工作负载 - -# 步骤一：配置权限 -### 1. 关闭firewall - Linux系统下面自带了防火墙iptables，iptables可以设置很多安全规则。但是如果配置错误很容易导致各种网络问题。此处建议关闭firewall。 -执行如下操作： -``` -sudo service firewalld stop -``` -执行完毕后结果应类似如下： - -![](https://oss.openanolis.cn/sig/eiaokzmkrqohrzcldbyh) - -### 2. 关闭selinux - Security-Enhanced Linux（SELinux）是一个在內核中实施的强制存取控制（MAC）安全性机制。 -为避免出现权限控制导致的虚拟机启动、访问失败等问题，此处建议关闭selinux。 -执行如下操作： -``` -sudo setenforce 0 -sudo sed -i 's/^SELINUX=enforcing$/SELINUX=permissive/' /etc/selinux/config -``` -执行成功后： -使用getenforce检查，结果应类似如下： - -![](https://oss.openanolis.cn/sig/wgkycimdpbhbeewmiqld) - -# 步骤二：安装kata 环境 - -Kata Containers是一个开源的、致力于用轻量级虚拟机构建一个安全的容器运行时的实现，这些虚拟机在感觉和执行上与容器类似，但使用硬件虚拟化技术作为第二层防御，提供了更强的工作负载隔离。 - -关于项目的更多信息，请参见[kata-container](https://github.com/confidential-containers/kata-containers-CCv0)。 - -## 1. 安装kata-containers - -1. 请执行以下命令，安装kata-containers。 -```shell -yum install -y kata-static -``` - -2. 运行以下命令，查看kata-containers是否安装成功。 -```shell -tree /opt/kata/ -``` - -返回结果示例如下，表示已安装成功。 - -![](https://oss.openanolis.cn/sig/bdpavhcztunbimlzvnuz) - -## 2. 安装qemu -此处使用的qemu基于6.2.0构建。 -```shell -yum install -y qemu-system-x86_64 -``` -## 3. 安装guest kernel，initrd，ovmf -ccv0-guest中包含kata运行CSV VM所需的guest kernel、initrd、OVMF、cmdline等文件。 -其中： -guest的rootfs和kernel，需使用efi_secret的内核模块以支持向文件系统中注入secret，加入AA并修改AA设置，自行构建请参考[guest Rootfs and Kernel](https://github.com/confidential-containers/documentation/blob/main/demos/sev-demo/README.md#rootfs-and-kernel) ； -这里提供的OVMF是基于f0f3f5aae7c4d346ea5e24970936d80dc5b60657 进行构建的，也可以使用[edk2-stable202108](https://github.com/tianocore/edk2/releases/tag/edk2-stable202108)后的版本自行构建，以支持CSV。 - -```shell -yum install -y ccv0-guest -``` - -cmdline中记录了CSV VM启动时所需的参数信息，需根据实际使用情况进行修改。可参考以下命令： -```sh -cat < -- 预期结果如下： - -```shell -SME is enabled! -CSV is enabled! -``` - - - -## 背景信息 - -![cncc](../../../../assets/csv_overview.png) - -CSV Pod 级机密容器架构基于 Kata Containers 项目，最大区别是将基于普通虚拟化技术实现的轻量级 Sandbox Pod替换为基于机密计算技术实现的轻量级 TEE Pod，目的是将特定租户的整个 Pod 以及其中的容器运行在受 CPU TEE 保护的执行环境中。除此之外，TEE Pod 内部还额外集成了 image-rs 和 attestation-agent 等组件，它们负责实现容器镜像的拉取、授权、验签、解密、远程证明以及秘密注入等安全特性。 -机密容器的基本运行过程为： - -- 用户使用标准工具制作一个签名和/或加密的受保护的容器镜像，并上传到容器镜像仓库中。 -- 用户命令 Kubernetes 启动这个受保护的容器镜像。kubelet 会向 containerd 发起创建 Pod 的 CRI 请求，containerd 则把请求转发给 kata-runtime。 -- kata runtime 与 Key broker service（simple kbs）建立安全会话，并进行基于CPU TEE 硬件的身份认证与授权。KBS基于安全可信信道发送敏感数据给kata runtime。kata runtime 调用QEMU 将秘密信息注入到guest userland中。之后再调用 QEMU 启动 Pod。 -- CPU TEE 执行初始化，最终启动 kata-agent 监听后续请求。 -- kubelet 向 containerd 发起 Image Pulling 的 CRI 请求，containerd 则把请求转发给 kata-runtime，最终 kata-agent 收到请求并通过 image-rs 子模块提供的容器镜像管理功能，在 TEE 内安全地执行拉取、验签、解密、unpack 以及挂载容器镜像的操作。 - -## 步骤一：部署测试集群 - -### 运行一键部署脚本 - -``` -sudo su root -cd hygon-devkit/csv/confidential-containers -./deploy-confidential_containers-0.5.0.sh -``` - -> 部署相关的详细内容请参考[Anolis OS 8.6部署支持CSV机密容器的k8s](./Anolis OS 8.6部署支持CSV机密容器的k8s.md)。 - -## 步骤二：启动Simple KBS - -[simple kbs](https://github.com/confidential-containers/simple-kbs#readme)是一个密钥代理服务，可以存储并向 workload 提供 secret 。对于 CSV 加密容器示例来说，需要从simple kbs 中获取 secret ，并用于解密已加密的容器。 -在步骤三的示例二中，本文提供了一个简单的加密镜像( docker.io/pawsonfang/busybox:encrypted )，该镜像使用 simple kbs 已经存在的密钥来解密，同时对 policy 不进行校验。此加密镜像只作为测试使用，如您想用于自己的生产用例中，请参考文档[制作一个新的加密镜像并部署](./制作一个新的加密镜像并部署.md)。 - -要了解有关创建 policy 的更多信息，请参考[自定义simple-kbs的policy](./自定义simple-kbs的policy.md)。 - -```shell -cd /opt/simple-kbs -sudo docker compose up -d -``` - -## 步骤三：运行workload - -attestation agent 支持三种CSV平台相关的KBC：[offline_fs_kbc](https://github.com/confidential-containers/attestation-agent/tree/main/kbc/src/offline_fs_kbc), [offline_sev_kbc](https://github.com/confidential-containers/attestation-agent/tree/main/kbc/src/offline_sev_kbc) 和 [online_sev_kbc](https://github.com/confidential-containers/attestation-agent/tree/main/kbc/src/online_sev_kbc)。 - -- offline fs KBC 事先把密钥放置在initrd中，用于验签容器镜像。缺点是每次更新密钥或policy，需要重新制作initrd。 -- offline sev KBC 在**运行时**不会与 Simple KBS 进行通信，而是使用在**VM Boot时期**通过QEMU注入的secret。该机制的缺点是对注入的 secret 长度有限制。 -- online sev KBC 在offline sev KBC的基础上，支持在**运行时**发出请求。online sev KBC 在VM Boot时期通过QEMU注入connection。注入的connection包含一个对称密钥，用于加密和验证 KBC 发出的在线请求。 该连接受 CSV秘密注入过程保护，该过程提供机密性、完整性并防止重放攻击。 simple-kbs 为每个连接生成一个新的对称密钥。 KBC 要求每个在线secret都带有随机 guid 以防止重放攻击。 - -> 本文以online_sev_kbc为主，oflline_sev_kbc 请参考[使用offline_sev_kbc模式运行加密容器](./使用offline_sev_kbc模式运行加密容器.md)，offline_fs_kbc 请参考[使用offline_fs_kbc模式运行签名容器](./使用offline_fs_kbc模式运行签名容器.md) - -### 示例一：运行一个未加密的容器镜像 - -为了验证主机上不存在容器镜像，应该登录到 k8s 节点并确保以下命令返回空结果： - -```shell -sudo crictl -r unix:///run/containerd/containerd.sock image ls | grep bitnami/nginx -``` - -启动POD - -```shell -cat <<-EOF | kubectl apply -f - -apiVersion: v1 -kind: Pod -metadata: - labels: - run: nginx - name: nginx -spec: - containers: - - image: bitnami/nginx:1.22.0 - name: nginx - dnsPolicy: ClusterFirst - runtimeClassName: kata -EOF -``` - -预期结果： - -```shell -pod/nginx created -``` - -查看 pod 状态： - -```shell -kubectl get pods -``` - -预期结果如下，注意， STATUS 要是 Running 。 - -```shell -NAME READY STATUS RESTARTS AGE -nginx 1/1 Running 0 3m50s -``` - -### 示例二：运行一个加密容器 - -#### 基于online sev KBC运行加密容器 - -- 编辑 kata 配置文件(kata 的配置文件路径：/opt/confidential-containers/share/defaults/kata-containers/configuration-qemu-csv.toml)： - - - 设置simple-kbs的ip地址 - - ``` - kbs_ip="$(ip -o route get to 8.8.8.8 | sed -n 's/.*src \([0-9.]\+\).*/\1/p')" - sudo sed -i 's#^guest_pre_attestation_kbs_uri = .*#guest_pre_attestation_kbs_uri = "'$kbs_ip':44444"#' /opt/confidential-containers/share/defaults/kata-containers/configuration-qemu-csv.toml - ``` - - - 设置kbs_mod为online模式，initrd指向支持online_sev_kbc的 - - ``` - initrd = "/opt/confidential-containers/share/kata-containers/kata-ubuntu-20.04-csv-online_sev_kbc.initrd" - guest_pre_attestation_kbs_mode="online" - ``` - - -- 启动POD - -```shell -cat <<-EOF | kubectl apply -f - -apiVersion: v1 -kind: Pod -metadata: - labels: - run: test-en-online - name: test-en-online -spec: - containers: - - image: docker.io/pawsonfang/busybox:encrypted - name: test-en-online - imagePullPolicy: Always - dnsPolicy: ClusterFirst - restartPolicy: Never - runtimeClassName: kata-qemu-csv -EOF -``` - -- 查看 pod 是否启动成功： - -```shell -kubectl get pods -``` - -- 预期结果如下： - -```shell -NAME READY STATUS RESTARTS AGE -test-en-online 1/1 Running 0 146m -``` - -#### 基于offline sev KBC运行加密容器 - -请参考[使用offline_sev_kbc模式运行加密容器](./使用offline_sev_kbc模式运行加密容器.md) - -### 示例三：运行一个签名容器 - -> 示例采用已存在的签名镜像，想要制作新的签名镜像，请参考[制作一个新的签名镜像并部署](./制作一个新的签名镜像并部署.md)。 - -#### 基于online sev KBC运行签名容器 - -- 编辑kata配置文件(kata 的配置文件路径：/opt/confidential-containers/share/defaults/kata-containers/configuration-qemu-csv.toml) - -修改kata为online_sev_kbc模式，同时使能镜像验签功能： - -``` -initrd = "/opt/confidential-containers/share/kata-containers/kata-ubuntu-20.04-csv-online_sev_kbc.initrd" -guest_pre_attestation_kbs_mode="online" -kernel_params = "agent.config_file=/etc/agent-config.toml agent.enable_signature_verification=true " -``` - -- 启动 Pod - -```shell -cat <<-EOF | kubectl apply -f - -apiVersion: v1 -kind: Pod -metadata: - labels: - run: test-sign-online - name: test-sign-online -spec: - containers: - - image: docker.io/pawsonfang/mybusybox - name: test-sign-online - imagePullPolicy: Always - dnsPolicy: ClusterFirst - restartPolicy: Never - runtimeClassName: kata-qemu-csv -EOF -``` - -- 查看 pod 是否启动成功： - -```shell -kubectl get pods -``` - -- 预期结果如下： - -```shell -NAME READY STATUS RESTARTS AGE -test-sign-online 1/1 Running 0 31h -``` - -#### 基于offline fs KBC运行签名容器 - -请参考[使用offline_fs_kbc模式运行加密容器](./使用offline_fs_kbc模式运行签名容器.md) - - - -## 附录 - -> 对于一些私人仓库，需要登录，才能下载镜像，具体方法请参考[CC场景如何下载需要auth的镜像](./CC场景如何下载需要auth的镜像.md)。 diff --git "a/DEVELOPER_DOCS/\346\265\267\345\205\211\345\256\211\345\205\250\350\231\232\346\213\237\345\214\226\346\212\200\346\234\257CSV/CSV\346\234\272\345\257\206\345\256\271\345\231\250-0.5.0/Anolis OS 8.6\351\203\250\347\275\262\346\224\257\346\214\201CSV\346\234\272\345\257\206\345\256\271\345\231\250\347\232\204k8s.md" "b/DEVELOPER_DOCS/\346\265\267\345\205\211\345\256\211\345\205\250\350\231\232\346\213\237\345\214\226\346\212\200\346\234\257CSV/CSV\346\234\272\345\257\206\345\256\271\345\231\250-0.5.0/Anolis OS 8.6\351\203\250\347\275\262\346\224\257\346\214\201CSV\346\234\272\345\257\206\345\256\271\345\231\250\347\232\204k8s.md" deleted file mode 100644 index 08f07c5b88e37962bbcc6a51cf94c420fbd5cda4..0000000000000000000000000000000000000000 --- "a/DEVELOPER_DOCS/\346\265\267\345\205\211\345\256\211\345\205\250\350\231\232\346\213\237\345\214\226\346\212\200\346\234\257CSV/CSV\346\234\272\345\257\206\345\256\271\345\231\250-0.5.0/Anolis OS 8.6\351\203\250\347\275\262\346\224\257\346\214\201CSV\346\234\272\345\257\206\345\256\271\345\231\250\347\232\204k8s.md" +++ /dev/null @@ -1,444 +0,0 @@ -# Anolis OS 8.6部署支持CSV机密容器的k8s - -本文主要为您介绍如何基于安全加密虚拟化CSV技术，部署k8s环境。 - -## 前提条件 - -### 1. 下载依赖 - -[hygon-devkit]([anolis/hygon-devkit - 码云 - 开源中国 (gitee.com)](https://gitee.com/anolis/hygon-devkit/tree/master))中包含了部署CSV机密容器需要的脚本和相关组件的rpm包 - -``` -git clone https://gitee.com/anolis/hygon-devkit.git -``` - -### 2. 使能安全功能 - -#### 安装安全工具hag - -hag 是 CSV 平台的命令行管理工具，请按照以下步骤安装 hag： - -```shell -cd hygon-devkit/csv/confidential-containers/ -sudo rpm -ivh --nodeps RPMs/hag-1.0.1868-1.x86_64.rpm -``` - -#### 导入通用安全证书 - -只有导入通用安全证书，才能开启安全功能，如CSV、TPM等 - -``` -sudo /opt/hygon/bin/hag general hgsc_import -``` - - - -## 步骤一：部署测试集群 - -本步骤为您提供快速部署**单节点测试集群**的步骤。您可以根据您的需求，灵活部署集群。 - -### 配置权限 - -#### 启用br_netfilter - -``` -# 临时启用 -sudo modprobe br_netfilter -# 永久启用 -echo "br_netfilter" > /etc/modules-load.d/br_netfilter.conf -``` - -#### 启用vhost-vsock/vhost-net - -``` -# 临时启用 -modprobe vhost-vsock -modprobe vhost-net -# 永久启用 -echo "vhost-vsock vhost-net" > /etc/modules-load.d/vhost.conf -``` - -#### 关闭firewall - -Linux系统下面自带了防火墙iptables，iptables可以设置很多安全规则。但是如果配置错误很容易导致各种网络问题。此处建议关闭firewall。 执行如下操作： - -``` -# 临时关闭 -sudo service firewalld stop -# 关闭自启动 -systemctl disable firewalld.service -``` - -检查 firewall 状态： - -```shell -service firewalld status -``` - -预期结果如下： - -```shell -Redirecting to /bin/systemctl status firewalld.service -● firewalld.service - firewalld - dynamic firewall daemon - Loaded: loaded (/usr/lib/systemd/system/firewalld.service; disabled; vendor preset: enabled) - Active: inactive (dead) - Docs: man:firewalld(1) -``` - -#### 关闭selinux - -Security-Enhanced Linux（SELinux）是一个在内核中实施的强制存取控制（MAC）安全性机制。为避免出现权限控制导致的虚拟机启动、访问失败等问题，此处建议关闭selinux。执行如下操作： - -```shell -# 临时关闭，重启失效 -setenforce 0 -# 永久关闭 -sudo sed -i 's/^SELINUX=enforcing$/SELINUX=permissive/' /etc/selinux/config -``` - -预期结果如下： - -```shell -setenforce: SELinux is disabled -``` - -#### 允许 iptables 检查桥接流量 - -``` -cat < /etc/containerd/config.toml -``` - -由于默认的 config.toml 使用的是国外的镜像，国内有可能无法访问。请参考以下命令修改为国内镜像。 - -```shell -sed -i 's#registry.k8s.io/pause:3.6#registry.cn-hangzhou.aliyuncs.com/google_containers/pause:3.6#g' /etc/containerd/config.toml -``` - -启动 containerd - -```shell -systemctl daemon-reload -systemctl enable --now containerd -systemctl status containerd -``` - -### 部署单节点的Kubernetes cluster - -- 请参考[kubernetes](https://github.com/kubernetes/kubernetes)官方指南安装Kubernetes cluster。最低 Kubernetes 版本应为 1.24。 - -``` -cat < configuration-qemu.toml - ├── kata-containers - │ ├── config-5.19.2 - │ ├── kata-containers.img -> kata-ubuntu-latest.image - │ ├── kata-containers-initrd-csv.img -> kata-ubuntu-20.04-csv-online_sev_kbc.initrd - │ ├── kata-ubuntu-20.04-csv-offline_fs_kbc.initrd - │ ├── kata-ubuntu-20.04-csv-offline_sev_kbc.initrd - │ ├── kata-ubuntu-20.04-csv-online_sev_kbc.initrd - │ ├── kata-ubuntu-latest.image - │ ├── vmlinux-5.19.2-102cc - │ ├── vmlinux-5.19.2-102cc-csv - │ ├── vmlinux.container -> vmlinux-5.19.2-102cc - │ ├── vmlinux-csv.container -> vmlinux-5.19.2-102cc-csv - │ ├── vmlinuz-5.19.2-102cc - │ ├── vmlinuz-5.19.2-102cc-csv - │ ├── vmlinuz.container -> vmlinuz-5.19.2-102cc - │ └── vmlinuz-csv.container -> vmlinuz-5.19.2-102cc-csv - ├── kata-qemu - │ └── qemu - │ ├── bios-256k.bin - │ ├── bios.bin - │ ├── bios-microvm.bin - │ ├── edk2-aarch64-code.fd - │ ├── edk2-arm-code.fd - │ ├── edk2-arm-vars.fd - │ ├── edk2-i386-code.fd - │ ├── edk2-i386-secure-code.fd - │ ├── edk2-i386-vars.fd - │ ├── edk2-licenses.txt - │ ├── edk2-x86_64-code.fd - │ ├── edk2-x86_64-secure-code.fd - │ ├── efi-virtio.rom - │ ├── firmware - │ │ ├── 50-edk2-i386-secure.json - │ │ ├── 50-edk2-x86_64-secure.json - │ │ ├── 60-edk2-aarch64.json - │ │ ├── 60-edk2-arm.json - │ │ ├── 60-edk2-i386.json - │ │ └── 60-edk2-x86_64.json - │ ├── hppa-firmware.img - │ ├── kvmvapic.bin - │ ├── linuxboot.bin - │ ├── linuxboot_dma.bin - │ ├── multiboot_dma.bin - │ ├── pvh.bin - │ ├── qboot.rom - │ ├── qemu-nsis.bmp - │ ├── s390-ccw.img - │ ├── s390-netboot.img - │ ├── vof.bin - │ └── vof-nvram.bin - └── ovmf - ├── HYGONCSV.fd - └── OVMF.fd -``` - -### containerd配置文件中添加kata - -``` -vim /etc/containerd/config.toml -``` - -打开配置文件，末尾添加下面的内容 - -``` -[plugins."io.containerd.grpc.v1.cri".containerd.runtimes.kata] - cri_handler = "" - runtime_type = "io.containerd.kata.v2" - privileged_without_host_devices = true - pod_annotations = ["io.katacontainers.*"] - [plugins."io.containerd.grpc.v1.cri".containerd.runtimes.kata.options] - ConfigPath = "/opt/confidential-containers/share/defaults/kata-containers/configuration.toml" -[plugins."io.containerd.grpc.v1.cri".containerd.runtimes.kata-qemu] - cri_handler = "cc" - runtime_type = "io.containerd.kata.v2" - privileged_without_host_devices = true - pod_annotations = ["io.katacontainers.*"] - [plugins."io.containerd.grpc.v1.cri".containerd.runtimes.kata-qemu.options] - ConfigPath = "/opt/confidential-containers/share/defaults/kata-containers/configuration-qemu.toml" -[plugins."io.containerd.grpc.v1.cri".containerd.runtimes.kata-qemu-csv] - cri_handler = "cc" - runtime_type = "io.containerd.kata.v2" - privileged_without_host_devices = true - pod_annotations = ["io.katacontainers.*"] - [plugins."io.containerd.grpc.v1.cri".containerd.runtimes.kata-qemu-csv.options] - ConfigPath = "/opt/confidential-containers/share/defaults/kata-containers/configuration-qemu-csv.toml" -``` - -### 重启containerd - -``` -sudo systemctl daemon-reload -sudo systemctl restart containerd -``` - -### 为k8s创建对应的RuntimeClass - -``` -cat <<-EOF | kubectl apply -f - -apiVersion: node.k8s.io/v1 -kind: RuntimeClass -metadata: - name: kata -handler: kata -EOF - -cat <<-EOF | kubectl apply -f - -apiVersion: node.k8s.io/v1 -kind: RuntimeClass -metadata: - name: kata-qemu -handler: kata-qemu -EOF - -cat <<-EOF | kubectl apply -f - -apiVersion: node.k8s.io/v1 -kind: RuntimeClass -metadata: - name: kata-qemu-csv -handler: kata-qemu-csv -EOF -``` - -检查创建的 RuntimeClasses。 - -```shell -kubectl get runtimeclass -``` - -预期结果如下： - -```shell -NAME HANDLER AGE -kata kata 23s -kata-qemu kata-qemu 11s -kata-qemu-csv kata-qemu-csv 5s -``` - -### 安装simple-kbs - -``` -cd hygon-devkit/csv/confidential-containers/ -sudo rpm -ivh --nodeps RPMs/simple-kbs-0.5.0-1.x86_64.rpm -``` - -#### 导出CSV证书链 - -Kata 机密容器需要 CSV 证书链从而与guest owner建立安全会话。CSV 证书链必须放在 /opt/csv 中，使用以下命令导出 CSV 证书链： - -```shell -sudo su -mkdir -p /opt/csv -/opt/hygon/bin/hag csv export_cert_chain -cat pdh.cert pek.cert oca.cert cek.cert hsk.cert hrk.cert > /opt/csv/cert_chain.cert -``` - diff --git "a/DEVELOPER_DOCS/\346\265\267\345\205\211\345\256\211\345\205\250\350\231\232\346\213\237\345\214\226\346\212\200\346\234\257CSV/CSV\346\234\272\345\257\206\345\256\271\345\231\250-0.5.0/CC\345\234\272\346\231\257\345\246\202\344\275\225\344\270\213\350\275\275\351\234\200\350\246\201auth\347\232\204\351\225\234\345\203\217.md" "b/DEVELOPER_DOCS/\346\265\267\345\205\211\345\256\211\345\205\250\350\231\232\346\213\237\345\214\226\346\212\200\346\234\257CSV/CSV\346\234\272\345\257\206\345\256\271\345\231\250-0.5.0/CC\345\234\272\346\231\257\345\246\202\344\275\225\344\270\213\350\275\275\351\234\200\350\246\201auth\347\232\204\351\225\234\345\203\217.md" deleted file mode 100644 index f8b2230c719abf39c19c0fd7332148eceeb49b34..0000000000000000000000000000000000000000 --- "a/DEVELOPER_DOCS/\346\265\267\345\205\211\345\256\211\345\205\250\350\231\232\346\213\237\345\214\226\346\212\200\346\234\257CSV/CSV\346\234\272\345\257\206\345\256\271\345\231\250-0.5.0/CC\345\234\272\346\231\257\345\246\202\344\275\225\344\270\213\350\275\275\351\234\200\350\246\201auth\347\232\204\351\225\234\345\203\217.md" +++ /dev/null @@ -1,66 +0,0 @@ -# CC场景如何下载需要auth的镜像 - -> 对于一些私人仓库，需要登录，才能下载镜像，所以需要添加账号的credential信息到kbs或initrd中。 - -## 添加您的账号信息到docker_auth_config.json - -``` -# 首先获取账户名密码的base64 encode,比如： -$ echo "pawsonfang:Passw0rd123" | base64 -cGF3c29uZmFuZzpQYXNzdzByZDEyMwo= -``` - -## 更新到docker_auth_config.json - -``` -{ - "https://index.docker.io/v1/": { - "auth": "bGl1ZGFsaWJqOlBhc3N3MHJkIXFhego=" - }, - "quay.io": { - "auth": "bGl1ZGFsaWJqOlBhc3N3MHJkIXFhego=" - }, - "docker.io": { - "auth": "cGF3c29uZmFuZzpQYXNzdzByZDEyMwo=" - } -} -``` - -## 更新信息到kbs或initrd - -> 对于online_sev_kbc/offline_fs_kbc，更新信息到kbs中； -> -> 对于offline_fs_kbc，更新信息到initrd； - -### online_sev_kbc/offline_fs_kbc - -- 获取simple-kbs的container id - - ``` - KBS_CID=$(sudo docker ps -aqf "name=^simple-kbs-server") - ``` - - - -- 更新json文件到simple-kbs - - ``` - cd /opt/simple-kbs/resources - sudo docker cp docker_auth_config.json ${KBS_CID}:/usr/local/bin/resources/docker_auth_config.json - ``` - - - -### offline_fs_kbc - -- 解包initrd - -- 将新的json文件的base64更新到resource.json - - ``` - cat /path/to/docker_auth_config.json | base64 --wrap=0 - # 把输出更新到etc/aa-offline_fs_kbc-resources.json的default/credential/test字段 - ``` - -- 打包initrd - diff --git "a/DEVELOPER_DOCS/\346\265\267\345\205\211\345\256\211\345\205\250\350\231\232\346\213\237\345\214\226\346\212\200\346\234\257CSV/CSV\346\234\272\345\257\206\345\256\271\345\231\250-0.5.0/photo1.jpg" "b/DEVELOPER_DOCS/\346\265\267\345\205\211\345\256\211\345\205\250\350\231\232\346\213\237\345\214\226\346\212\200\346\234\257CSV/CSV\346\234\272\345\257\206\345\256\271\345\231\250-0.5.0/photo1.jpg" deleted file mode 100644 index a81c13c4e470a8e7b189c11f37d22b25181bcff8..0000000000000000000000000000000000000000 Binary files "a/DEVELOPER_DOCS/\346\265\267\345\205\211\345\256\211\345\205\250\350\231\232\346\213\237\345\214\226\346\212\200\346\234\257CSV/CSV\346\234\272\345\257\206\345\256\271\345\231\250-0.5.0/photo1.jpg" and /dev/null differ diff --git "a/DEVELOPER_DOCS/\346\265\267\345\205\211\345\256\211\345\205\250\350\231\232\346\213\237\345\214\226\346\212\200\346\234\257CSV/CSV\346\234\272\345\257\206\345\256\271\345\231\250-0.5.0/\344\275\277\347\224\250offline_fs_kbc\346\250\241\345\274\217\350\277\220\350\241\214\347\255\276\345\220\215\345\256\271\345\231\250.md" "b/DEVELOPER_DOCS/\346\265\267\345\205\211\345\256\211\345\205\250\350\231\232\346\213\237\345\214\226\346\212\200\346\234\257CSV/CSV\346\234\272\345\257\206\345\256\271\345\231\250-0.5.0/\344\275\277\347\224\250offline_fs_kbc\346\250\241\345\274\217\350\277\220\350\241\214\347\255\276\345\220\215\345\256\271\345\231\250.md" deleted file mode 100644 index 140a688a257844cbe68646dfd0908fdd99f6a5e2..0000000000000000000000000000000000000000 --- "a/DEVELOPER_DOCS/\346\265\267\345\205\211\345\256\211\345\205\250\350\231\232\346\213\237\345\214\226\346\212\200\346\234\257CSV/CSV\346\234\272\345\257\206\345\256\271\345\231\250-0.5.0/\344\275\277\347\224\250offline_fs_kbc\346\250\241\345\274\217\350\277\220\350\241\214\347\255\276\345\220\215\345\256\271\345\231\250.md" +++ /dev/null @@ -1,48 +0,0 @@ -# 使用offline_fs_kbc模式运行签名容器.md - -> offline_fs_kbc模式，是把验签公钥放在initrd中，不需要借助于simple-kbs，相应的，也就不支持pre_attestation - -- 编辑kata配置文件(kata 的配置文件路径：/opt/confidential-containers/share/defaults/kata-containers/configuration-qemu-csv.toml。) - -设置kbc_mode，initrd指向offline_fs_kbc模式的initrd，关闭pre_attestation功能，使能镜像验签功能： - -``` -initrd = "/opt/confidential-containers/share/kata-containers/kata-ubuntu-20.04-csv-offline_fs_kbc.initrd" -guest_pre_attestation = false -kernel_params = "agent.aa_kbc_params=offline_fs_kbc::null agent.enable_signature_verification=true " -``` - -- 启动 Pod - -```shell -cat <<-EOF | kubectl apply -f - -apiVersion: v1 -kind: Pod -metadata: - labels: - run: test-sign-offline - name: test-sign-offline -spec: - containers: - - image: docker.io/pawsonfang/mybusybox - name: test-sign-offline - imagePullPolicy: Always - dnsPolicy: ClusterFirst - restartPolicy: Never - runtimeClassName: kata-qemu-csv -EOF -``` - -- 查看 pod 是否启动成功： - -```shell -kubectl get pods -``` - -- 预期结果如下： - -```shell -NAME READY STATUS RESTARTS AGE -test-sign-offline 1/1 Running 0 31h -``` - diff --git "a/DEVELOPER_DOCS/\346\265\267\345\205\211\345\256\211\345\205\250\350\231\232\346\213\237\345\214\226\346\212\200\346\234\257CSV/CSV\346\234\272\345\257\206\345\256\271\345\231\250-0.5.0/\344\275\277\347\224\250offline_sev_kbc\346\250\241\345\274\217\350\277\220\350\241\214\345\212\240\345\257\206\345\256\271\345\231\250.md" "b/DEVELOPER_DOCS/\346\265\267\345\205\211\345\256\211\345\205\250\350\231\232\346\213\237\345\214\226\346\212\200\346\234\257CSV/CSV\346\234\272\345\257\206\345\256\271\345\231\250-0.5.0/\344\275\277\347\224\250offline_sev_kbc\346\250\241\345\274\217\350\277\220\350\241\214\345\212\240\345\257\206\345\256\271\345\231\250.md" deleted file mode 100644 index fe6a2822d4515c154b3efe10b7a3b1a2c2a1869f..0000000000000000000000000000000000000000 --- "a/DEVELOPER_DOCS/\346\265\267\345\205\211\345\256\211\345\205\250\350\231\232\346\213\237\345\214\226\346\212\200\346\234\257CSV/CSV\346\234\272\345\257\206\345\256\271\345\231\250-0.5.0/\344\275\277\347\224\250offline_sev_kbc\346\250\241\345\274\217\350\277\220\350\241\214\345\212\240\345\257\206\345\256\271\345\231\250.md" +++ /dev/null @@ -1,45 +0,0 @@ -# 使用offline_sev_kbc模式运行加密容器.md - -- kata配置文件默认配置为online模式，请修改为下面的字段，使其为offline模式： - - ``` - initrd = "/opt/confidential-containers/share/kata-containers/kata-ubuntu-20.04-csv-offline_sev_kbc.initrd" - guest_pre_attestation_kbs_mode="offline" - ``` - -- 自定义 policy ，请参考[自定义simple-kbs的policy](./自定义simple-kbs的policy.md)。 - - -- 启动 Pod - -```shell -cat <<-EOF | kubectl apply -f - -apiVersion: v1 -kind: Pod -metadata: - labels: - run: test-en-offline - name: test-en-offline -spec: - containers: - - image: docker.io/pawsonfang/busybox:encrypted - name: test-en-offline - imagePullPolicy: Always - dnsPolicy: ClusterFirst - restartPolicy: Never - runtimeClassName: kata-qemu-csv -EOF -``` - -- 查看 pod 是否启动成功： - -```shell -kubectl get po -``` - -- 预期结果如下： - -```shell -NAME READY STATUS RESTARTS AGE -test-en-offline 1/1 Running 0 31h -``` diff --git "a/DEVELOPER_DOCS/\346\265\267\345\205\211\345\256\211\345\205\250\350\231\232\346\213\237\345\214\226\346\212\200\346\234\257CSV/CSV\346\234\272\345\257\206\345\256\271\345\231\250-0.5.0/\345\210\266\344\275\234\344\270\200\344\270\252\346\226\260\347\232\204\345\212\240\345\257\206\351\225\234\345\203\217\345\271\266\351\203\250\347\275\262.md" "b/DEVELOPER_DOCS/\346\265\267\345\205\211\345\256\211\345\205\250\350\231\232\346\213\237\345\214\226\346\212\200\346\234\257CSV/CSV\346\234\272\345\257\206\345\256\271\345\231\250-0.5.0/\345\210\266\344\275\234\344\270\200\344\270\252\346\226\260\347\232\204\345\212\240\345\257\206\351\225\234\345\203\217\345\271\266\351\203\250\347\275\262.md" deleted file mode 100644 index 8d0139a512cea19ead1aad672d41948bbf3b7d3f..0000000000000000000000000000000000000000 --- "a/DEVELOPER_DOCS/\346\265\267\345\205\211\345\256\211\345\205\250\350\231\232\346\213\237\345\214\226\346\212\200\346\234\257CSV/CSV\346\234\272\345\257\206\345\256\271\345\231\250-0.5.0/\345\210\266\344\275\234\344\270\200\344\270\252\346\226\260\347\232\204\345\212\240\345\257\206\351\225\234\345\203\217\345\271\266\351\203\250\347\275\262.md" +++ /dev/null @@ -1,193 +0,0 @@ -# 制作一个新的加密镜像并部署 - -本文主要为您介绍如何制作一个新的加密镜像，并部署pod。 - -#### 安装依赖 - -需要借助[skopeo](https://github.com/containers/skopeo)加密容器镜像，安装步骤如下： - -``` -# 安装go，用于编译 -sudo yum install go -y -# 安装git、make等依赖 -sudo yum install git make gcc gpgme-devel libassuan-devel device-mapper-devel -y -# 源码安装skopeo -git clone https://github.com/containers/skopeo $(go env GOPATH)/src/github.com/containers/skopeo -cd $(go env GOPATH)/src/github.com/containers/skopeo -DISABLE_DOCS=1 make bin/skopeo -sudo DISABLE_DOCS=1 make install -# 检查命令可用 -skopeo -v -``` - -#### 加密镜像 - -Attestation Agent可以启动一个grpc服务来支持对映像进行加密。克隆仓库: - -``` -attestation_agent_tag="v0.5.0" -git clone https://github.com/confidential-containers/attestation-agent.git -(cd attestation-agent && git checkout -b "branch_${attestation_agent_tag}" "${attestation_agent_tag}") -``` - -编译并启动CoCo Keyprovider: - -``` -# 安装依赖 -curl https://sh.rustup.rs -sSf | sh -source "$HOME/.cargo/env" -sudo yum install openssl-devel -y -# 编译并启动 -cd attestation-agent/coco_keyprovider -RUST_LOG=coco_keyprovider cargo run --release -- --socket 127.0.0.1:50000 -``` - -创建 Attestation Agent keyprovider: - -``` -cat > ocicrypt.conf < key1 -``` - -把你想要加密的镜像加密并拷贝到当前目录，本例中使用的是`busybox`镜像。其中密钥使用`keypath`指定，`keyid`此处设置为`kbs:///default/key/key_id2`，密钥算法设置为`A256GCM`，`——insecure-policy`标志用于连接到认证代理，不会影响项目的安全性。 - -``` -OCICRYPT_KEYPROVIDER_CONFIG=ocicrypt.conf skopeo copy --insecure-policy --encryption-key provider:attestation-agent:keypath=$(pwd)/key1::keyid=kbs:///default/key/key_id2::algorithm=A256GCM docker://busybox oci:busybox:encrypted -``` - -加密后，可以看到在当前目录下生成了`busybox`目录。 - -确认镜像确实已经被加密： - -``` -cat ./busybox/index.json | python3 -m json.tool -``` - -xxxxxxxxxx NAME               READY   STATUS   RESTARTS   AGEtest-en-offline     1/1     Running   0         31hshell - -``` -{ - "schemaVersion": 2, - "manifests": [ - { - "mediaType": "application/vnd.oci.image.manifest.v1+json", - "digest": "sha256:f594fcb13ca12e4ebf400b5e8ab715cb4f30adb335b8e31366d61f5350029e6e", - "size": 1195, - "annotations": { - "org.opencontainers.image.ref.name": "encrypted" - } - } - ] -} -``` - -根据digest找到对应的manifest：`./busybox/blocs/sha256/73135775766027c5006e7744fa8007e812afec905064743c68b780dd49c1eeaf` - -``` -cat ./busybox/blobs/sha256/f594fcb13ca12e4ebf400b5e8ab715cb4f30adb335b8e31366d61f5350029e6e | python3 -m json.tool -``` - -期望结果： - -``` -{ - "schemaVersion": 2, - "mediaType": "application/vnd.oci.image.manifest.v1+json", - "config": { - "mediaType": "application/vnd.oci.image.config.v1+json", - "digest": "sha256:3488e6e2e41e62fc51be840cd61d806d5b45defdb84a2e6c99ea8a0edb4b6cc7", - "size": 575 - }, - "layers": [ - { - "mediaType": "application/vnd.oci.image.layer.v1.tar+gzip+encrypted", - "digest": "sha256:0dfdc90a4529ca0b38e575945748d6f8258ad2ea2cce8755b8a9f0e1566e447f", - "size": 2592227, - "annotations": { - "org.opencontainers.image.enc.keys.provider.attestation-agent": "eyJraWQiOiJrYnM6Ly8vZGVmYXVsdC90ZXN0LWtleS8xIiwid3JhcHBlZF9kYXRhIjoiLzNMeWhsdVE1aG42MVVjN0ZDM1BWTlNDUlV0YitLc1h5ZWhGTERtaUJlcUE4cStrcGgxbFpwckR4cjh0ck5RUFpxRDB2UlFobVFFWTM1YnV3R05VeGRINXdyeWtCa0x2OTFkSHFHMEJOY1FETVNhNTBBZFpqb00xTHQ0SUdIUDlZeEpGL3hmcWk4RFFBUmdXNjhpV3hlcWgxTFRMQ01hcUg5TzUxeXduYmcxTmJ3aFM0aXdkRSttMGRhOWwyTXpqeklrbjRtN3pWZUl6cFRVVHJuS0gyM1RmWmVWZUZsZVMxY0VscWhGdGw4bnZDYmphNlZyQlFYTzRFVVZUdjkvemxzS2xnRnl3aEhnL1VvUHBmMXMvY2RJPSIsIml2IjoiQUFBQUFBQUFBQUFBQUFBQSIsIndyYXBfdHlwZSI6IkEyNTZHQ00ifQ==", - "org.opencontainers.image.enc.pubopts": "eyJjaXBoZXIiOiJBRVNfMjU2X0NUUl9ITUFDX1NIQTI1NiIsImhtYWMiOiJqWHhYMGVWWGR2RHAxbVpxSHVXYzFJWGFwazhicmhKMHdpbDl5K3JLUXc4PSIsImNpcGhlcm9wdGlvbnMiOnt9fQ==" - } - } - ] -} -``` - -其中`mediaType`为`application/vnd.oci.image.layer.v1.tar+gzip+encrypted`，表示该layer已被加密。 - -#### 上传镜像到远程的image registry - -记得把docker.io/myrepo替换为自己的仓库地址： - -``` -# 登录您的image registry，比如登录docker.io -skopeo login docker.io -# 上传镜像 -skopeo copy --insecure-policy oci:busybox:encrypted docker://docker.io/myrepo/busybox:encrypted -``` - -#### 更新密钥到kbs - -- 设置数据库参数 - - ``` - KBS_DB_USER="kbsuser" - KBS_DB_PW="kbspassword" - KBS_DB="simple_kbs" - KBS_DB_TYPE="mysql" - KBS_DB_HOST=$(sudo docker network inspect simple-kbs_default \ - | jq -r '.[].Containers[] | select(.Name | test("simple-kbs[_-]db.*")).IPv4Address' \ - | sed "s|/.*$||g") - ``` - -- 获取加密密钥的base64 encode - -```shell -enc_key=$(cat key1 | base64) -echo $enc_key -``` - -- 将 加密密钥 注入 mysql 中。 - -```shell -mysql -u${KBS_DB_USER} -p${KBS_DB_PW} -h ${KBS_DB_HOST} -D ${KBS_DB} < 注意：`default/key/key_id2`要与skopeo参数相同；使用offline_sev_kbc时，要设置`configuration-qemu-csv.toml`中`guest_pre_attestation_keyset`的值为`KEYSET-2` - -#### 使用新的加密镜像启动pod - -> myrepo替换为自己的仓库地址 - -``` -cat <<-EOF | kubectl apply -f - -apiVersion: v1 -kind: Pod -metadata: - labels: - run: test-en-online2 - name: test-en-online2 -spec: - containers: - - image: docker.io/myrepo/busybox:encrypted - name: test-en-online2 - imagePullPolicy: Always - dnsPolicy: ClusterFirst - restartPolicy: Never - runtimeClassName: kata-qemu-csv -EOF -``` - diff --git "a/DEVELOPER_DOCS/\346\265\267\345\205\211\345\256\211\345\205\250\350\231\232\346\213\237\345\214\226\346\212\200\346\234\257CSV/CSV\346\234\272\345\257\206\345\256\271\345\231\250-0.5.0/\345\210\266\344\275\234\344\270\200\344\270\252\346\226\260\347\232\204\347\255\276\345\220\215\351\225\234\345\203\217\345\271\266\351\203\250\347\275\262.md" "b/DEVELOPER_DOCS/\346\265\267\345\205\211\345\256\211\345\205\250\350\231\232\346\213\237\345\214\226\346\212\200\346\234\257CSV/CSV\346\234\272\345\257\206\345\256\271\345\231\250-0.5.0/\345\210\266\344\275\234\344\270\200\344\270\252\346\226\260\347\232\204\347\255\276\345\220\215\351\225\234\345\203\217\345\271\266\351\203\250\347\275\262.md" deleted file mode 100644 index 195b4afd74889e673c0a64679a6b73b73a7ae43a..0000000000000000000000000000000000000000 --- "a/DEVELOPER_DOCS/\346\265\267\345\205\211\345\256\211\345\205\250\350\231\232\346\213\237\345\214\226\346\212\200\346\234\257CSV/CSV\346\234\272\345\257\206\345\256\271\345\231\250-0.5.0/\345\210\266\344\275\234\344\270\200\344\270\252\346\226\260\347\232\204\347\255\276\345\220\215\351\225\234\345\203\217\345\271\266\351\203\250\347\275\262.md" +++ /dev/null @@ -1,161 +0,0 @@ -# 制作一个新的签名镜像并部署 - -本文主要为您介绍如何制作一个新的签名镜像，并部署pod。 - -## 安装cosign - -``` -git clone https://github.com/sigstore/cosign -cd cosign -go install ./cmd/cosign -$(go env GOPATH)/bin/cosign -``` - -## 准备镜像 - -> 示例中使用docker.io存放签名镜像 - -``` -# 使用自己的账号、密码登录 -sudo docker login -# 以busybox为例 -sudo docker pull busybox -# YOUR_USER替换为自己的用户名，YOUR_IMAGE替换为自己想要命名的image name -sudo docker image tag busybox docker.io/YOUR_USER/YOUR_IMAGE -sudo docker push docker.io/YOUR_USER/YOUR_IMAGE -``` - -## 使用cosign签名镜像 - -``` -$(go env GOPATH)/bin/cosign generate-key-pair -# 输入密码，密码是用来加密私钥的 -$(go env GOPATH)/bin/cosign login docker.io --username YOUR_USER -sudo $(go env GOPATH)/bin/cosign sign --key cosign.key docker.io/YOUR_USER/YOUR_IMAGE -``` - -## 自定义policy.json - -> 创建一个新的policy.json，自定义image的pull规则，如下面示例所示，注意keyPath对应的位置用于索引公钥。 - -``` -{ - "default": [{"type": "insecureAcceptAnything"}], - "transports": { - "docker": { - "docker.io/pawsonfang/mybusybox": [ - { - "type": "sigstoreSigned", - "keyPath": "kbs:///default/cosign-public-key/test" - } - ], - "docker.io/pawsonfang/busybox_signed": [ - { - "type": "sigstoreSigned", - "keyPath": "kbs:///default/cosign-public-key/test2" - } - ] - } - } -} -``` - -## 根据kbc_mod更新公钥和policy - -> 对于online_sev_kbc，将公钥和policy添加到数据库； -> -> 对于offline_fs_kbc，将公钥和policy更新到initrd中。 - -### online_sev_kbc - -- 获取simple-kbs的container id - - ``` - KBS_CID=$(sudo docker ps -aqf "name=^simple-kbs-server") - ``` - - - -- 更新policy文件和公钥文件到simple-kbs - - ``` - cd /opt/simple-kbs/resources - sudo docker cp /path/to/policy.json ${KBS_CID}:/usr/local/bin/resources/image_pull_policy.json - sudo docker cp /path/to/cosign.pub ${KBS_CID}:/usr/local/bin/resources/cosign2.pub - ``` - -- 设置数据库参数 - - ``` - KBS_DB_USER="kbsuser" - KBS_DB_PW="kbspassword" - KBS_DB="simple_kbs" - KBS_DB_TYPE="mysql" - KBS_DB_HOST=$(sudo docker network inspect simple-kbs_default \ - | jq -r '.[].Containers[] | select(.Name | test("simple-kbs[_-]db.*")).IPv4Address' \ - | sed "s|/.*$||g") - ``` - - 插入新的公钥keyid:resource_path信息到数据库中 - - ``` - mysql -u${KBS_DB_USER} -p${KBS_DB_PW} -h ${KBS_DB_HOST} -D ${KBS_DB} < ../initrd.new.img -gzip ../initrd.new.img -cd ../ && mv initrd.new.img.gz initrd.new.img -cp initrd.new.img /opt/confidential-containers/share/kata-containers/kata-ubuntu-20.04-csv-offline_fs_kbc.initrd -``` - -#### 使用新的image启动pod，此处以online_sev_kbc为例 - -> YOUR_USER/YOUR_IMAGE替换为自己的镜像地址 - -``` -cat <<-EOF | kubectl apply -f - -apiVersion: v1 -kind: Pod -metadata: - labels: - run: test-sign-online2 - name: test-sign-online2 -spec: - containers: - - image: docker.io/YOUR_USER/YOUR_IMAGE - name: test-sign-online2 - imagePullPolicy: Always - dnsPolicy: ClusterFirst - restartPolicy: Never - runtimeClassName: kata-qemu-csv -EOF -``` - diff --git "a/DEVELOPER_DOCS/\346\265\267\345\205\211\345\256\211\345\205\250\350\231\232\346\213\237\345\214\226\346\212\200\346\234\257CSV/CSV\346\234\272\345\257\206\345\256\271\345\231\250-0.5.0/\350\207\252\345\256\232\344\271\211simple-kbs\347\232\204policy.md" "b/DEVELOPER_DOCS/\346\265\267\345\205\211\345\256\211\345\205\250\350\231\232\346\213\237\345\214\226\346\212\200\346\234\257CSV/CSV\346\234\272\345\257\206\345\256\271\345\231\250-0.5.0/\350\207\252\345\256\232\344\271\211simple-kbs\347\232\204policy.md" deleted file mode 100644 index def57a8ff53153a0ded5ec4d624973073b511793..0000000000000000000000000000000000000000 --- "a/DEVELOPER_DOCS/\346\265\267\345\205\211\345\256\211\345\205\250\350\231\232\346\213\237\345\214\226\346\212\200\346\234\257CSV/CSV\346\234\272\345\257\206\345\256\271\345\231\250-0.5.0/\350\207\252\345\256\232\344\271\211simple-kbs\347\232\204policy.md" +++ /dev/null @@ -1,83 +0,0 @@ -# 自定义simple KBS 的policy - -- /opt/confidential-containers/bin/csv-measure.py是一个实用程序，用于使用提供的 ovmf、initrd、kernel、cmdline等作为参数来计算 CSV guest固件测量值。 - -- 计算内核的append值（需要先启动一个offline_sev_kbc或online_sev_kbc的pod） - -```shell -duration=$((SECONDS+30)) -set append - -while [ $SECONDS -lt $duration ]; do - qemu_process=$(ps aux | grep qemu | grep append || true) - if [ -n "${qemu_process}" ]; then - append=$(echo ${qemu_process} \ - | sed "s|.*-append \(.*$\)|\1|g" \ - | sed "s| -.*$||") - break - fi - sleep 1 -done - -echo "${append}" > cmdline_file -``` - -- 根据ovmf、kernel、initrd_path和cmdline_file的地址设置参数。 - - ovmf、kernel和initrd_path的地址请参考kata 的配置文件 - - kata 的配置文件路径：/opt/confidential-containers/share/defaults/kata-containers/configuration-qemu-csv.toml。 - -```shell -ovmf_path="/opt/confidential-containers/share/ovmf/HYGONCSV.fd" -kernel_path="/opt/confidential-containers/share/kata-containers/vmlinuz-csv.container" -initrd_path="/opt/confidential-containers/share/kata-containers/kata-ubuntu-20.04-csv-online_sev_kbc.initrd" -cmdline_path=${PWD}/cmdline_file -``` - -- 使用csv-measure.py 来计算 CSV guest 的Launch digest。 - -```shell - #安装依赖 - sudo pip3 install snowland-smx - #计算digest - measurement=$(/opt/confidential-containers/bin/csv-measure.py \ - --ovmf "${ovmf_path}" \ - --kernel "${kernel_path}" \ - --initrd "${initrd_path}" \ - --cmdline "${cmdline_path}" \ -) -# 确认measurement计算成功 -echo $measurement -``` - -- 设置simple kbs 数据库参数 - -```shell -KBS_DB_USER="kbsuser" -KBS_DB_PW="kbspassword" -KBS_DB="simple_kbs" -KBS_DB_TYPE="mysql" -KBS_DB_HOST=$(sudo docker network inspect simple-kbs_default \ - | jq -r '.[].Containers[] | select(.Name | test("simple-kbs[_-]db.*")).IPv4Address' \ - | sed "s|/.*$||g") -``` - -- 由于本文使用的加密镜像( docker.io/pawsonfang/busybox:encrypted )，是采用 simple kbs 已经存在的密钥来解密，该镜像的 enc_key 值如下。用户需要根据加密镜像按需设置enc_key。 - -```shell -enc_key=C1z522QYM9YZDcz+7nstjYD2HNX1/2/okVStRA2ChDo= -``` - -- 将 自定义policy 注入 mysql 中。 - - policy的组成包括：digests、policies、api_major、api_minor、build_ids等信息。详情请参考[链接](https://github.com/confidential-containers/simple-kbs/blob/main/db/db-mysql.sql#L73)。 - - 我们以digests为例子，向用户展示如何注入自定义policy 。用户可以根据需求自定义Policy。 - -```shell -# 安装依赖 -yum install mysql -y -mysql -u${KBS_DB_USER} -p${KBS_DB_PW} -h ${KBS_DB_HOST} -D ${KBS_DB} <New/File a Bug->Select a classification->Select a product->Bug创建页面。具体如下：首先，在首页点击New或File a Bug按钮，进行创建Bug。 - 然后会提示让选择一个classification, classification是Bug的一级分类。 \ No newline at end of file diff --git "a/OPERATIONS_DOCS/\344\272\272\344\272\272\351\203\275\345\217\257\344\273\245\345\217\202\344\270\216\345\274\200\346\272\220/\346\223\215\344\275\234\345\271\263\345\217\260/nothing.jpg" "b/OPERATIONS_DOCS/\344\272\272\344\272\272\351\203\275\345\217\257\344\273\245\345\217\202\344\270\216\345\274\200\346\272\220/\346\223\215\344\275\234\345\271\263\345\217\260/nothing.jpg" deleted file mode 100644 index a81c13c4e470a8e7b189c11f37d22b25181bcff8..0000000000000000000000000000000000000000 Binary files "a/OPERATIONS_DOCS/\344\272\272\344\272\272\351\203\275\345\217\257\344\273\245\345\217\202\344\270\216\345\274\200\346\272\220/\346\223\215\344\275\234\345\271\263\345\217\260/nothing.jpg" and /dev/null differ diff --git "a/OPERATIONS_DOCS/\344\272\272\344\272\272\351\203\275\345\217\257\344\273\245\345\217\202\344\270\216\345\274\200\346\272\220/\346\223\215\344\275\234\345\271\263\345\217\260/windows\345\271\263\345\217\260.md" "b/OPERATIONS_DOCS/\344\272\272\344\272\272\351\203\275\345\217\257\344\273\245\345\217\202\344\270\216\345\274\200\346\272\220/\346\223\215\344\275\234\345\271\263\345\217\260/windows\345\271\263\345\217\260.md" deleted file mode 100644 index de2fbe7fecb7f0699bd67544a32f750fa2f44cf9..0000000000000000000000000000000000000000 --- "a/OPERATIONS_DOCS/\344\272\272\344\272\272\351\203\275\345\217\257\344\273\245\345\217\202\344\270\216\345\274\200\346\272\220/\346\223\215\344\275\234\345\271\263\345\217\260/windows\345\271\263\345\217\260.md" +++ /dev/null @@ -1,78 +0,0 @@ -# 一级标题 - -## 二级标题 - -### 三级标题 - -tupiantttt------------ - -#### 四级标题 - -##### 五级标题 - -###### 六级标题 - -## 二. 图片一 -![nothing](../../人人都可以参与开源/操作平台/nothing.jpg) -*** -## 三. 图片2 -![](../../人人都可以参与开源/操作平台/nothing.jpg) -*** -## 三. 图片2-1 -![](./nothing.jpg) -*** -## 四. 图片3 -图片3 - -*** -图片3 - ---- - -*斜体文字* - -_斜体文字_ - -**粗体文字** - -__粗体文字__ - -***粗斜体文字*** - -___粗斜体文字___ - - -*** -* * * -****** -- - - ------- - -baidu.com -sina.com -~~tencent.com~~ - - - -* 第一项 -* 第二项 -* 第三项 - -+ 第一项 -+ 第二项 -+ 第三项 - -- 第一项 -- 第二项 -- 第三项 - -1. 第一项： - - 第一项嵌套的第一个元素 - - 第一项嵌套的第二个元素 -2. 第二项： - - 第二项嵌套的第一个元素 - - 第二项嵌套的第二个元素 - -> 区块引用 -> Markdown教程 -> 学的不仅是技术更是梦想 \ No newline at end of file diff --git "a/OPERATIONS_DOCS/\344\272\272\344\272\272\351\203\275\345\217\257\344\273\245\345\217\202\344\270\216\345\274\200\346\272\220/\351\276\231\350\234\245\344\270\200\345\210\273/\344\272\214\345\210\206\346\263\225/Anolis OS\347\216\257\345\242\203\346\220\255\345\273\272\346\225\231\347\250\213.md" "b/OPERATIONS_DOCS/\344\272\272\344\272\272\351\203\275\345\217\257\344\273\245\345\217\202\344\270\216\345\274\200\346\272\220/\351\276\231\350\234\245\344\270\200\345\210\273/\344\272\214\345\210\206\346\263\225/Anolis OS\347\216\257\345\242\203\346\220\255\345\273\272\346\225\231\347\250\213.md" deleted file mode 100644 index a9f7ecb382957f8fb98b0d231d69b48f1efed377..0000000000000000000000000000000000000000 --- "a/OPERATIONS_DOCS/\344\272\272\344\272\272\351\203\275\345\217\257\344\273\245\345\217\202\344\270\216\345\274\200\346\272\220/\351\276\231\350\234\245\344\270\200\345\210\273/\344\272\214\345\210\206\346\263\225/Anolis OS\347\216\257\345\242\203\346\220\255\345\273\272\346\225\231\347\250\213.md" +++ /dev/null @@ -1,268 +0,0 @@ -# 写在前面 - -Anolis OS 是 OpenAnolis 社区推出的完全开源、中立、开放的发行版，它支持多计算架构，也面向云端场景优化。 - -在您使用Anolis OS之前，我们提供了一个预装Anolis OS的在线机器资源服务。我们**强烈建议**您访问[**龙蜥实验室**](https://lab.openanolis.cn/#/apply/home)，使用Web页面及机器人等形式自动创建和管理机器资源，以此来对Anolis OS进行体验。 - -您可以访问[龙蜥实验室使用指南](https://www.yuque.com/anolis-docs/community/peng85)，来进行**一键申请**和 **免费试用** 。 - -![](https://intranetproxy.alipay.com/skylark/lark/0/2022/png/63156315/1656644119956-01a1cabe-eb42-4c64-82d8-902d01afb26d.png) - -我们提供两种方式安装Anolis OS： - -* ISO镜像安装 -* qcow虚拟机镜像安装 - -## 一、通过ISO进行安装 - -### 1.1 ISO镜像下载 - -登陆下载界面获取Anolis OS最新iso镜像文件 - -[https://openanolis.cn/download](https://openanolis.cn/download) - -![](https://intranetproxy.alipay.com/skylark/lark/0/2022/png/63156315/1656504756808-2cdce132-2ff8-4d66-a96d-18cd6525601a.png) - -### 1.2 镜像安装 - -参考该文档，通过图形化安装接口部署Anolis8/7至目标平台： - -[https://www.yuque.com/anolis-docs/manual/installation](https://www.yuque.com/anolis-docs/manual/installation) - -## 二、 通过qcow虚拟机镜像安装 - -首先，验证CPU是否支持KVM； - -`egrep '(vmx|svm)' /proc/cpuinfo` - -如果结果中有vmx（Intel）或svm(AMD)字样，就说明CPU是支持的。 - -如果您是买的ECS，或者已经开了虚拟机，那大概率没办法再通过KVM的方式进行安装。 - -### 2.1 虚拟机镜像下载 - -登陆下载界面获取Anolis OS最新qcow2镜像文件 - -[https://openanolis.cn/download](https://openanolis.cn/download) - -这里以7.9为例：点击网址中的下载按钮后，选择相应架构的文件夹进入，既可以看到对应的下载列表，请选择**AnolisOS-7.9-GA-x86_64-ANCK.qcow2**文件进行下载。 - -![](https://intranetproxy.alipay.com/skylark/lark/0/2022/png/63156315/1656574325523-958feb42-fbbf-4974-9bd9-9d6827dd99db.png) - -### 2.2 安装依赖包 - -`sudo yum install -y qemu-kvm libvirt virt-install bridge-utils` - -### 2.3 启动前配置 - -#### 2.3.1 libvirt服务 - -开启libvirt服务 - -`systemctl start libvirtd` - -设置开机启动 - -`systemctl enable libvirtd` - -查看状态操作结果 - -`systemctl status libvirtd` - -![](https://intranetproxy.alipay.com/skylark/lark/0/2022/png/63156315/1656557798218-65ab7a31-63e2-4200-bca5-2ed9f65a169e.png) - -`systemctl is-enabled libvirtd` - -![](https://intranetproxy.alipay.com/skylark/lark/0/2022/png/63156315/1656557863822-cec7389f-3748-43c9-8878-e03fe5906f4f.png) - -#### 2.3.2 打开虚拟化的网络支持 - -`sudo virsh net-autostart default` - -`sudo virsh net-start default` - -`sudo sysctl -w net.ipv4.ip_forward=1` # 也可以写到配置文件里持久化 - -**TIPS：** - -`sudo virsh net-autostart default` 执行过程中可能会卡住，此时将 `/etc/modprobe.d/blacklist.conf` 文件中的 "blacklist nf_conntrack_ipv4" 语句注释掉，例如 - -``` -... -#blacklist nf_conntrack_ipv4 -``` - -之后再执行 `sudo virsh net-autostart default` - -#### 2.3.3 修改kvm权限 - -直接设置成root启动 - -``` -cat >> /etc/libvirt/qemu.conf << EOF -user = "root" -group = "root" -EOF -systemctl restart libvirtd.service -``` - -#### 2.3.4 建立链接 - -查看qemu-kvm路径 - -`whereis qemu-kvm` - -``` -qemu-kvm: /etc/qemu-kvm /usr/libexec/qemu-kvm /usr/share/qemu-kvm /usr/share/man/man1/qemu-kvm.1.gz -``` - -建立软连接 - -`ln -s /usr/libexec/qemu-kvm /usr/bin/qemu-kvm` - -#### 2.3.5 创建xml配置文件 - -示例文件的名称为anolis.xml，请根据提示修改您的镜像路径 - -您可以按照注释自己酌情修改。 - -``` - - anolis - 16777216 - 8 - - - - - hvm - - - - - - - - - - - - destroy - restart - restart - - - /usr/bin/qemu-kvm - - - - - - - - - - - - - - - - - - - - - - - - - - - -``` - -### 2.4 虚拟机的启动与管理 - -#### 2.4.1 使用virsh命令启动虚拟机 - -新机器执行virsh命令可能会有setlocale: No such file or directory的警告，可安装语言包 - -`yum install -y glibc-langpack-zh` - -`sudo virsh define 虚拟机名.xml` - -`sudo virsh start 虚拟机名` # 请修改为KVM虚拟机的真实名称。 - -vm 默认的账户和密码为： - -* 用户名：`anuser` -* 密码：`anolisos` - -#### 2.4.2 切换root用户并允许ssh root登录 - -1. `sudo su` -2. 输入密码`anolisos` -3. 修改root密码：`passwd root` -4. 修改`/etc/ssh/sshd_config`: - -``` -PasswordAuthentication yes - -PermitRootLogin yes -``` - -#### 2.4.3 虚拟机的访问 - -可以通过下列方式访问VM: - -* 通过 vnc 访问宿主机的 IP，登录VM，查看 IP -* 通过 `sudo virsh console 虚拟机名` 登录 VM（请注意可能会有一段时间的黑屏，VM启动过程没有输出到屏幕），查看 IP -* 获取到 Guest IP 之后，通过 `ssh root@` 登录 VM. - -#### 2.4.3 查询虚拟机在宿主机对应串口设备 - -`virsh ttyconsole 虚拟机名` - -#### 2.4.4 其余virsh命令 - -`virsh list` #显示本地活动虚拟机 - -`virsh list –-all ` #显示本地所有的虚拟机（活动的+不活动的） - -`virsh define 虚拟机名.xml` #通过配置文件定义一个虚拟机（这个虚拟机还不是活动的） - -`virsh undefine 虚拟机名.xml` #删除虚拟机配置 - -`virsh start 虚拟机名` #启动名字为ubuntu的非活动虚拟机 - -`virsh create 虚拟机名.xml ` # 创建虚拟机（创建后，虚拟机立即执行，成为活动主机） - -`virsh suspend 虚拟机名` # 暂停虚拟机 - -`virsh resume 虚拟机名 ` # 启动暂停的虚拟机 - -`virsh shutdown 虚拟机名` # 正常关闭虚拟机 - -`virsh destroy 虚拟机名` # 强制关闭虚拟机 - -`virsh dominfo 虚拟机名` #显示虚拟机的基本信息 - -`virsh domname 2` # 显示id号为2的虚拟机名 - -`virsh domid 虚拟机名` # 显示虚拟机id号 - -`virsh domuuid 虚拟机名` # 显示虚拟机的uuid - -`virsh domstate 虚拟机名` # 显示虚拟机的当前状态 - -`virsh dumpxml 虚拟机名` # 显示虚拟机的当前配置文件（可能和定义虚拟机时的配置不同，因为当虚拟机启动时，需要给虚拟机分配id号、uuid、vnc端口号等等） - -`virsh setmem 虚拟机名 512000` #给不活动虚拟机设置内存大小 - -`virsh setvcpus 虚拟机名 4` # 给不活动虚拟机设置cpu个数 - -`virsh edit 虚拟机名` # 编辑配置文件（一般是在刚定义完虚拟机之后） diff --git "a/OPERATIONS_DOCS/\344\272\272\344\272\272\351\203\275\345\217\257\344\273\245\345\217\202\344\270\216\345\274\200\346\272\220/\351\276\231\350\234\245\344\270\200\345\210\273/\344\272\214\345\210\206\346\263\225/\351\276\231\350\234\245 ANCK 5.10 \345\200\232\345\244\251\345\271\263\345\217\260 MPAM \346\265\213\350\257\225\346\212\245\345\221\212.md" "b/OPERATIONS_DOCS/\344\272\272\344\272\272\351\203\275\345\217\257\344\273\245\345\217\202\344\270\216\345\274\200\346\272\220/\351\276\231\350\234\245\344\270\200\345\210\273/\344\272\214\345\210\206\346\263\225/\351\276\231\350\234\245 ANCK 5.10 \345\200\232\345\244\251\345\271\263\345\217\260 MPAM \346\265\213\350\257\225\346\212\245\345\221\212.md" deleted file mode 100644 index b3230c28ce258110ce76f3dd8cbfa7c1c036a7e2..0000000000000000000000000000000000000000 --- "a/OPERATIONS_DOCS/\344\272\272\344\272\272\351\203\275\345\217\257\344\273\245\345\217\202\344\270\216\345\274\200\346\272\220/\351\276\231\350\234\245\344\270\200\345\210\273/\344\272\214\345\210\206\346\263\225/\351\276\231\350\234\245 ANCK 5.10 \345\200\232\345\244\251\345\271\263\345\217\260 MPAM \346\265\213\350\257\225\346\212\245\345\221\212.md" +++ /dev/null @@ -1,1001 +0,0 @@ -from arm-sig: https://openanolis.cn/sig/ARM_ARCH_SIG/doc/657742613244594693 - -一、测试总结 - -针对龙蜥 OS MPAM 特性的整体测试情况如下： - -经过对 MPAM 的功能性验证，目前 L3 cache 资源隔离和监控功能均正常，内存带宽隔离效果甚微，监控功能可用。 -测试用例覆盖 MPAM 接口读写测试、并发压力测试等多种类型，测试结果未发现问题。 -针对 MPAM ESR 中断，验证了 PARTID、PMG、monitor 相关异常能否触发中断、告知错误类型，中断监测功能正常可用。 -二、MPAM 功能验证 -2.1 cache 隔离功能验证 -2.1.1 不同配置对实际 cache 占有量的影响 - -L3 cache 资源隔离以 ways 的方式进行配置。倚天机器共有 16 ways，测试对不同 ways 的隔离效果进行了验证。 - -numactl -m 0 -C 16 memhog -r10000000 100000m > /mnt/log - -程序和资源隔离 group 绑定分别采用了 pid 绑定（tasks）和 cpu 绑定（cpus）两种方式。通过 schemata 接口设置程序所能够使用的 ways 数目，通过 mon_data/mon_L3_0*/llc_occupancy 接口读取程序的 L3 cache 占用。多次读取取平均值，并与理想的 cache ways 大小进行对比。 - -测试结果显示，L3 cache 隔离功能效果显著，无论是通过 tasks 绑定还是 cpus 绑定，均可以得到与理想值相接近的隔离效果。 - -2.1.2 不同配置对 mem latency 的影响 - -latency 作为一个重要的性能指标，在一些对时延敏感的场景来说，有很重要的参考作用，此处使用 lat_mem_rd 测试 cache 在不同的 ways 下，内存 latency 的分布情况，也从侧面验证 MPAM 对 cache 的隔离功能。 - -#设置步长为512字节 -numactl -C 10 -m 0 ./lat_mem_rd -N 1 -P 1 145M 512 - -测试结果显示，随着 cache way 数目的增加，加载相同内存的 latency 逐渐减小。 - -2.1.3 L3 cache 抗干扰测试 -# workload -numactl -m 1 -C 64-127 memhog -r10000000 100000m > /mnt/log -# distractor -numactl -m 1 -C 64-127 memhog -r10000000 100000m > /mnt/log - -workload：保持 L3:1=fff0 配置无变化 - -distractor: 测试 L3:1=，mask 值分别为 0-f（无干扰）、0010-fff0（有干扰） - -测试结果显示： - -在无干扰情况下，workload 的 L3 cache 占用量基本无变化； - -随着干扰 way 数逐渐变多，workload 和 distractor 两者的 L3 cache占比逐渐趋同，总量不变。 - -2.1.4 模拟混部 L3 cache 隔离测试 - -分别以 SPECjbb 2015 和 stress-ng 程序模拟在线环境和离线环境，对L3 cache隔离功能进行测试。两个环境均运行在 NUMA node 1 上。 - -在前 40s 的时间内，两个程序共享 L3 cache 资源。在约 40s 后，开始隔离在线和离线L3 cache资源的使用，在离线任务 L3 cache 的配比分别为 0xffff 和 0xf。 - -通过实验结果可以看到，在 L3 cache 资源共享的情况下，离线资源对在线资源干扰和压制明显，L3 cache 竞争激烈，波动幅度很大；在对 L3 cache 资源进行隔离后，一方面离线得到了持续有效的压制，L3 cache 占有率大幅下降，另一方面在线性能提升明显，而且波动幅度变小。 - -2.2 MB 隔离功能验证 -2.2.1 不同配置对内存带宽的影响 -gcc -O3 -fopenmp -DSTREAM_ARRAY_SIZE=100000000 -DNTIMES=1000 stream.c -o stream -# 单node测试 -numactl -m 1 -C 64-127 ./stream -# 单CPU测试 -numactl -m 1 -C 72 ./stream - -MB 资源隔离以百分比的方式进行配置。测试以 5% 为粒度，通过设置 schemata 接口让内存带宽从 5% 逐次递增到 100%，通过读取 mon_data/mon_MB_0*/mbm_local_bytes 接口读取带宽值，最终取多次测量的平均值。 - -通过测试结果可以发现，不同百分比下的测试MB带宽值和100%带宽下的MB带宽值基本相等，倚天机器的 MB 带宽隔离效果甚微。 - -单 node（64 CPU） MB 配置结果 - -percent - - - -stream测试值[Copy] (MB/s) - - - -mbm_local_bytes接口值 (MB/s) - - - - -5 - - - -104808.5 - - - -104800.0 - - - - -10 - - - -105028.3 - - - -105730.5 - - - - -20 - - - -104459.3 - - - -104915.1 - - - - -40 - - - -105077.6 - - - -105852.0 - - - - -60 - - - -104980.6 - - - -105178.7 - - - - -80 - - - -104924.8 - - - -105182.8 - - - - -100 - - - -104828.1 - - - -105855.8 - -单 CPU MB 配置结果 - -percent - - - -stream测试值[Copy] (MB/s) - - - -mbm_local_bytes接口值 (MB/s) - - - - -5 - - - -25948.7 - - - -24147.7 - - - - -10 - - - -25934.0 - - - -24433.1 - - - - -20 - - - -25913.5 - - - -22771.2 - - - - -40 - - - -25897.9 - - - -24559.4 - - - - -60 - - - -25952.9 - - - -24079.7 - - - - -80 - - - -25866.5 - - - -24246.4 - - - - -100 - - - -25952.1 - - - -24171.9 - -三、MPAM稳定性测试 -3.1 resctrl mount/umount - -测试方法 - -挂载 resctrl 文件系统，设置 schemata 资源隔离接口，随机写 cpus/cpus_list、tasks 接口，读取mon_data 资源监控接口，最后卸载 resctrl 文件系统。重复 1000000 次。 - -测试结果 - -resctrl 文件系统相关接口仍可正常使用。 - -3.2 接口写入测试 -3.2.1 schemata 写入 - -测试方法 - -创建两个 group，生成随机 L3 cache mask 和 MB 内存带宽值，并分别写入两个 group 的 schemata 接口，之后读取 schemata 接口，验证当前值是否与写入值相同。重复测试 1000000 次。 - -测试结果 - -schemata 均可正常写入。 - -3.2.2 schemata 错误写入 - -对 schemata 接口写入多种错误参数，验证 schemata 是否可以正确识别处理。 - -验证的错误类型及验证结果如下： - -错误写入示例 - - - -last_cmd_status输出 - - - -测试结果 - - - - -L3:0=10000 - - - -Mask out of range - - - -PASS - - - - -L3:2=ff;3=ff - - - -Unknown domain - - - -PASS - - - - -L3 - - - -Missing ':' - - - -PASS - - - - -L3: - - - -Missing 'L3' value - - - -PASS - - - - -L3:0 - - - -Missing '=' or non-numeric domain - - - -PASS - - - - -L30:0=fff - - - -Unknown or unsupported resource name 'L30' - - - -PASS - - - - -L3:0=fghi - - - -Non-hex character in the mask fghi - - - -PASS - - - - -L3:1=ff;1=f4 - - - -Duplicate domain 1 - - - -PASS - - - - -MB:0=150 - - - -MB value 150 out of range 5-100 - - - -PASS - - - - -MB:0=4 - - - -MB value 4 out of range 5-100 - - - -PASS - - - - -MB:0=FOO - - - -Non-decimal digit in MB - - - -PASS - - - - -MB - - - -Missing ':' - - - -PASS - - - - -MB:0 - - - -Missing 'MB' value - - - -PASS - - - - -MB:2=55 - - - -Unknown domain - - - -PASS - - - - -MB:1=23;1=56 - - - -Duplicate domain 1 - - - -PASS - - - - -L3:0=ff (with cdp) - - - -Unknown or unsupported resource name 'L3' - - - -PASS - -3.2.3 cpus/cpus_list 写入 - -测试方法 - -随机写入 cpus/cpus_list 接口 1000000 次，验证是否写入成功，并且 cpus 接口和 cpus_list 接口的值是否相对应。 - -测试结果 - -cpus/cpus_list 均可正常写入，并保持值的相等。 - -3.2.4 cpus/cpus_list 错误写入 - -错误写入示例 - - - -last_cmd_status输出 - - - -测试结果 - - - - -echo 156 > cpus_list - - - -Can only assign online CPUs - - - -PASS - - - - -echo 4096 > cpus_list - - - -Bad CPU list/mask - - - -PASS - - - - -echo ffff > cpus_list - - - -Bad CPU list/mask - - - -PASS - - - - -echo 3-12 > cpus - - - -Bad CPU list/mask - - - -PASS - -3.2.5 tasks 写入 - -测试方法 - -创建 500 个进程，并将其 pid 写入 tasks 接口，验证进程对应 pid 是否存在。之后 kill 掉所有进程，验证其 pid 是否已从 tasks 文件中移除。重复 1000000 次。 - -测试结果 - -tasks 接口均可正常写入和移除。 - -3.2.6 tasks 错误写入 - -错误示例 - - - -stderr - - - -测试结果 - - - - -将不存在pid写入tasks - - - -echo: write error: No such process - - - -PASS - - - - -echo hello > tasks - - - -echo: write error: Invalid argument - - - -PASS - -3.2.7 mode 写入 - -mode 接口默认值为 shareable，当前MPAM接口暂不支持 mode 接口值的修改。 - -Mode - - - -支持情况 - - - - -shareable - - - -支持 - - - - -exclusive - - - -不支持 - - - - -pseudo-locksetup - - - -不支持 - - - - -pseudo-locked - - - -不支持 - -3.3 group mkdir/rmdir 测试 -3.3.1 max group 创建 - -测试方法 - -以 info/*/num_closids 为基准，创建所能达到的最多 group。重复 1000000 次。 - -测试结果 - -倚天 PARTID 数目为 64 个，因此除了 default group 外，最多能够创建 63 个 group。一般情况下均可达到最大值。但在部分 group 被使用过的情况下，由于其对应的 PARTID 在 L3 cache中占用量可能超过 /sys/fs/resctrl/info/L3_MON/max_threshold_occupancy，从而导致该 PARTID 在一定时间内不可用。 - -3.3.2 group 随机创建/删除 - -测试方法 - -随机创建/删除 group 共计 2000*(num_closids-1)，验证 group 分配和回收功能是否正常。 - -测试结果 - -group 随机创建和删除，group 分配/回收接口仍可正常运作。 - -3.3.3 mon_group 创建/删除 - -当前社区版本MPAM代码下 num_rmids 均为 1，暂不支持 mon_groups 目录下 mon group 的创建和删除。 - -3.4 并发读写测试 -3.4.1 L3 cache 监控接口并发读取 - -测试方法 - -创建 5 个 group，每个 group 中写入 10 个进程：memhog -r1000000000 1m > /mnt/log - -同时 10 个进程并发读 mon_data/L3_MON/llc_occupancy，持续时间 60 min。 - -测试结果 - -测试过程中未出现resctrl接口崩溃或不可用问题。 - -3.4.2 MB 监控接口并发读取 - -测试方法 - -创建 5 个 group，每个 group 中写入 10 个进程：memhog -r1000000000 1m > /mnt/log - -同时 10 个进程并发读 mon_data/mon_MB_*/mbm_local_bytes，持续时间 60 min。 - -测试结果 - -测试过程中未出现 resctrl 接口崩溃或不可用问题。 - -3.4.3 schemata 接口并发写入 - -测试方法 - -创建 5 个 group，每个 group 中写入 10 个进程：memhog -r1000000000 1m > /mnt/log - -同时 10 个进程并发随机写入 schemata，持续时间 60 min。 - -测试结果 - -测试过程中未出现 resctrl 接口崩溃或不可用问题。 - -3.4.4 cpus/cpus_list 接口并发写入 - -测试方法 - -创建 1 个 group，10 个进程并发写入随机 cpus/cpus_list，持续时间 60 min。 - -测试结果 - -测试过程未出现接口崩溃或不可用问题。 - -3.4.5 tasks 接口并发写入 - -测试方法 - -创建 1 个 group，10 个进程并发创建 300 个 task 并写入 tasks 接口。 - -测试结果 - -测试过程未出现接口崩溃或不可用问题。 - -四、MPAM 错误中断验证 -4.1 L3 cache 资源错误中断验证 - -错误码 - - - -描述 - - - -结果 - - - -备注 - - - - -0 - - - -No error captured in MPAMF_ESR - - - -无 - - - -非异常情况 - - - - -1 - - - -MPAMCFG_PART_SEL out of range - - - -可触发 - - - - - - - - - -2 - - - -Request PARTID out of range - - - -可触发 - - - - - - - - - -3 - - - -MSMON out of range PARTID/PMG - - - -可触发 - - - - - - - - - -4 - - - -Request PMG out of range - - - -不可触发 - - - -PMG>1时无法写入 - - - - -5 - - - -MSMON_CFG_MON_SEL out of range - - - -可触发 - - - - - - - - - -6 - - - -MPAMCFG_INTPARTID out of range - - - -未测试 - - - -暂不支持PARTID narrowing - - - - -7 - - - -INTERNAL unexpected - - - -未测试 - - - -暂不支持PARTID narrowing - - - - -8 - - - -MPAMCFG_PART_SEL.RIS unimplemented - - - -不可触发 - - - -RIS>1时无法写入 - - - - -9 - - - -MPAMCFG_PART_SEL.RIS no control - - - -不可触发 - - - -RIS>1时无法写入 - - - - -10 - - - -MSMON_CFG_MON_SEL.RIS unimplemented - - - -不可触发 - - - -RIS>1时无法写入 - - - - -11 - - - -MSMON_CFG_MON_SEL.RIS no monitor - - - -不可触发 - - - -RIS>1时无法写入 - - - - -12:18 - - - -Reserved \ No newline at end of file diff --git "a/OPERATIONS_DOCS/\344\272\272\344\272\272\351\203\275\345\217\257\344\273\245\345\217\202\344\270\216\345\274\200\346\272\220/\351\276\231\350\234\245\344\270\200\345\210\273/\345\206\222\346\263\241\346\216\222\345\272\217/\346\235\203\347\233\212\347\273\206\345\210\231.md" "b/OPERATIONS_DOCS/\344\272\272\344\272\272\351\203\275\345\217\257\344\273\245\345\217\202\344\270\216\345\274\200\346\272\220/\351\276\231\350\234\245\344\270\200\345\210\273/\345\206\222\346\263\241\346\216\222\345\272\217/\346\235\203\347\233\212\347\273\206\345\210\231.md" deleted file mode 100644 index b151f17f61a29d4d6306dd6d001f760de4269fc8..0000000000000000000000000000000000000000 --- "a/OPERATIONS_DOCS/\344\272\272\344\272\272\351\203\275\345\217\257\344\273\245\345\217\202\344\270\216\345\274\200\346\272\220/\351\276\231\350\234\245\344\270\200\345\210\273/\345\206\222\346\263\241\346\216\222\345\272\217/\346\235\203\347\233\212\347\273\206\345\210\231.md" +++ /dev/null @@ -1,142 +0,0 @@ -什么是贡献值？ -龙蜥社区是一个操作系统开源社区，欢迎开发者们一起为社区做贡献，感受开源魅力。 - -近期，社区上线了【贡献值】功能。贡献值是根据你在社区的参与程度而发放的分值。例如，提升了社区文档的质量、分享你的开发者故事、给某一个SIG贡献了代码，等等，这些都是帮助社区成长，将会被赠与不同的贡献值。 - -你可以在社区的个人中心查看贡献值。其中： - -“总贡献值”是你在社区的历年贡献值的总数，见证你与社区的共同成长。 -“可兑换贡献值”是用于兑换权益的，它的初始分值等同于“总贡献值”，但会随着兑换而扣除相应分值。 -贡献值能做什么？ -贡献值可以兑换社区的权益。详细的兑换分值，请参见本文“如何获得贡献值？”一节。 - -用途一：申请实习证明或实践证明 -如果你是在校大学生、研究生，可申请实习证明 （贡献值需达到100分及以上）。实习证明由社区颁发，记录你在社区的贡献信息。 -如果你是在校中学生，可以申请实践证明 （贡献值需达到100分及以上）。实践证明由社区颁发，记录你在社区的贡献信息。 -实习证明/实践证明将于9月初开放申请 。根据贡献值的多少，证书分为“高级”、“中级”、“初级”。申请后，该证明会发放到你的个人中心，你也可通过编号在社区查询。 - -在200+社区生态企业（如阿里云、统信等单位）招聘期 ，参与龙蜥社区贡献是加分项 。如果你是应届生，持有实习证明，还有机会获得内推机会 ，为你寻找最合适的岗位。 - - -用途二：兑换社区的定制礼品 -龙蜥社区为开发者们准备了丰富的礼品，不同的分值可兑换不同价值的礼品。兑换礼品后， “可兑换贡献值”会相应减少，但“总贡献值”不会减少。 - -例如，你原有200积分，使用50分兑换了礼品，则“可兑换贡献值”变为150分，但“总贡献值”依旧是200分。 - - -用途三：参与年度评奖 -龙蜥社区将会围绕代码和非代码贡献评选出年度突出贡献奖，贡献值（“总贡献值”）将会是入围奖项的重要考核因素之一。 - - -更多权益，敬请期待。 - -如何获得贡献值？ -参与活动越多，贡献值越高，实习证明或礼品的等级越高。你可以通过以下参与方式来获得贡献值。 - -方式一：开启龙蜥社区之旅 -方式 获得标准 贡献值 -首次注册社区 注册龙蜥社区的账号。 5 -首次绑定Gitee账号 首次成功绑定龙蜥社区账号与Gitee账号。 5 -首次登录社区 首次登录龙蜥社区。 1 -首次浏览SIG详情 你的龙蜥社区账号，首次浏览≥3个SIG详情页面。 1 -首次阅读博客文章 你的龙蜥社区账号，首次阅读≥3篇博客文章。 1 -首次浏览新闻动态 你的龙蜥社区账号，首次阅读≥3篇新闻。 1 -首次学习视频 你的龙蜥社区账号，首次观看学习≥1个视频。 1 -首次了解龙蜥操作系统（Anolis OS） 你的龙蜥社区账号，首次浏览Anolis OS 产品页面，关注产品动态。 1 -首次阅读CentOS停服专区 你的龙蜥社区账号，首次阅读CentOS停服专区的内容，了解详情。 1 -首次下载龙蜥操作系统（Anolis OS） 你的龙蜥社区账号，首次下载Anolis OS到本地使用。 3 -首次了解龙蜥软硬件兼容能力 你的龙蜥社区账号，首次浏览软硬件兼容适配列表。 1 -首次了解龙蜥安全更新 你的龙蜥社区账号，首次浏览安全公告，查看Errata和CVEs。 1 -方式二：参与专项开发者活动，走进开源 -1. 推荐新人参与此活动 -推荐方式：在「人人都可以参与开源」活动页面的右侧，找到 分享 按钮，复制链接发送。被分享人完成任务后，你可以获得贡献值。 -分享按钮 - -2. 字字珠玑：文档捉虫 -目标：提交文档缺陷，优化文档质量。针对准确性、合规性、可读性、规范性等问题提交issue。 - -捉虫范围：SIG文档和CentOS停服专区文档 - -语言范围：简体中文 - -找出的文档缺陷类型 贡献值 -内容不合规，存在违法、违规内容。例如内容可能有版权纠纷、内容涉黄涉赌涉政等。 2 -内容/代码错误或缺失关键内容，导致操作中断，无法继续执行。 2 -内容/代码有误或不完整，但不影响操作。 1 -描述不清晰，例如语句有歧义或含义模糊。 1 -低错，例如链接失效、图片失效、有错别字、专有名词写法错误或写法不统一等。 1 -3. 字字珠玑：文档翻译 -目标：将中文文档翻译成英文。 - -翻译范围：SIG文档和CentOS停服专区文档 - -翻译标准：没有漏译，没有错译，没有明显的语法错误。 - -翻译的数量 贡献值 -每200字 1 -说明：每增加200字，贡献值增加1分。单篇上限为10分。 - -4. 字字珠玑：写文档 -目标：社区产品/基础设施的帮助文档、使用建议等。已有文档请参见Anolis OS产品文档 。 - -文档类型：使用社区产品/基础设施的最佳实践、FAQ、使用体验或建议反馈等。 - -要求： - -文档内容要准确，是经过测试或实践的。 -文档步骤尽可能详细。 -可以适当配上图片，更易于理解。 -文档内容 贡献值 -FAQ。 -你在使用龙蜥社区的任何产品（Anolis OS 7或8、KeenTune、龙蜥实验室、ABS等）、任何阶段（下载、部署、安装等）时碰到的问题。希望你提供详细的报错信息，如果有解决方案更佳。示例。 2~5 -最佳实践。 -你使用龙蜥社区产品的最佳实践，例如你是怎么玩转ABS、T-One的。希望你提供详细的操作步骤，让更多人用起来。示例 5~10 -使用社区产品的真实体验，以及建议反馈。 -在使用社区产品碰到的不好体验，可以记录下来并反馈给我们。 2~5 -5. 随机试炼 -获得标准 贡献值 -完成抽取到的盲盒任务，并提交PR。 1~20。以任务中标注的贡献值为准。 -6. 龙蜥一刻 -获得标准 贡献值 -完成领取的任务，并提交PR。 1~20。以任务中标注的贡献值为准。 -7. 一码当先 -获得标准 贡献值 -完成领取的任务，并提交PR。 1~10000。以任务中标注的贡献值为准。 -方式三：参与社区日常任务、热爱布道与分享 -方式 获得标准 贡献值 -积极参与SIG 成为SIG的maintainer。 50 -积极参与SIG 成为SIG的committer。 10 -投稿 投稿开发者故事、评测文章，针对文章质量发放贡献值。详情参考这里。 5~10 -直播分享 参与龙蜥大讲堂直播分享，每一次分享都会发放贡献值。详情参考这里。 20~100 -成为社区推广大使 根据每一次的推广类型与成效，发放贡献值。详情参考这里。 1~100 -如何查看贡献值？如何用贡献值兑换礼品？ -打开贡献值页面，或者在龙蜥社区官网右上角，点击账号头像，选择“我的贡献值”。页面上方显示你的贡献值。 - -找到贡献值旁边的“去兑换/申领”链接，填写兑换申请。 - -去兑换或申领 - -贡献值对应的权益等级 -权益一：实习证明与实习机会 -注意： - -申请实习证明或实践证明， 不会扣除贡献值。 -在200+社区生态企业（如阿里云、统信等单位）的招聘期间 ，参与龙蜥社区贡献是加分项 。如果你是应届生，持有实习证明，还有机会获得内推机会 ，为你寻找最合适的岗位。 -贡献值 可申请的实习证明/实践证明 -≥300 初级 -≥1000 中级 -≥2000 高级 -权益二：社区定制礼品 -可兑换的定制礼品（ 任选其一 ，先到先得） 消耗的贡献值 -帆布袋、小龙本子+笔、数据线、手机支架、小风扇、U盘、陶瓷杯、雨伞、小龙抱枕、T恤、U盘、加湿器等。 100 -书籍、咖啡保温杯、蓝牙音箱、小米鼠标、无线充鼠标垫、金属把手马克杯、双肩包、纽曼蓝牙耳机、眼罩脖枕套装、充电宝、筋膜枪等。 300 -极客时间企业版年度会员卡，罗技G502鼠标、猫王蓝牙音箱、beats耳机、罗技K845机械键盘等。 1000 -大疆云台，树莓派Pi 400电脑键盘PC一体机，罗技G610机械键盘等。 2000 -任天堂Switch NS日版，当贝投影仪，小米扫地机器人，cherry电竞键盘，airpods等。 年度总分前三名 -还可以兑换云服务器资源，当前可兑换的物品以龙蜥官网上的兑换页为准，持续上线中。 - -说明：如果某些礼品库存告罄，将会发放相似的礼品。 - -声明 -禁止恶意刷分，一经发现，将清空贡献值。 -活动解释权归龙蜥社区所有。 \ No newline at end of file diff --git "a/PRODUCT_DOCS/anolisos/23/\347\224\250\346\210\267\346\214\207\345\215\227/\350\247\243\345\206\263\346\226\271\346\241\210/641.jpg" "b/PRODUCT_DOCS/anolisos/23/\347\224\250\346\210\267\346\214\207\345\215\227/\350\247\243\345\206\263\346\226\271\346\241\210/641.jpg" deleted file mode 100644 index 4455b9fd8735efc80d12738345e026d71d33ab21..0000000000000000000000000000000000000000 Binary files "a/PRODUCT_DOCS/anolisos/23/\347\224\250\346\210\267\346\214\207\345\215\227/\350\247\243\345\206\263\346\226\271\346\241\210/641.jpg" and /dev/null differ diff --git "a/PRODUCT_DOCS/anolisos/23/\347\224\250\346\210\267\346\214\207\345\215\227/\350\247\243\345\206\263\346\226\271\346\241\210/LMP\351\241\271\347\233\256\344\273\213\347\273\215.md" "b/PRODUCT_DOCS/anolisos/23/\347\224\250\346\210\267\346\214\207\345\215\227/\350\247\243\345\206\263\346\226\271\346\241\210/LMP\351\241\271\347\233\256\344\273\213\347\273\215.md" deleted file mode 100644 index 16151f210c97a3791a7bbebb9d4d66b348c4e54f..0000000000000000000000000000000000000000 --- "a/PRODUCT_DOCS/anolisos/23/\347\224\250\346\210\267\346\214\207\345\215\227/\350\247\243\345\206\263\346\226\271\346\241\210/LMP\351\241\271\347\233\256\344\273\213\347\273\215.md" +++ /dev/null @@ -1,3 +0,0 @@ -面向 eBPF 初学者和爱好者，提供 eBPF 学习资料、程序/项目案例，构建 eBPF 学习社区 成为 eBPF 想象力集散地，我们相信每一位 eBPF 初学者和爱好者都有无限的想象力，一个想法、一段话甚至是一个问题都是你发挥想象力的方式 孵化 eBPF 想法、相关工具、项目 为实现我们的目标，目前 LMP 提供三个子项目，正在建设中，欢迎各位的建议 ^ ^ - -https://github.com/linuxkerneltravel/lmp \ No newline at end of file diff --git "a/PRODUCT_DOCS/anolisos/23/\347\224\250\346\210\267\346\214\207\345\215\227/\350\247\243\345\206\263\346\226\271\346\241\210/migration_solution.md" "b/PRODUCT_DOCS/anolisos/23/\347\224\250\346\210\267\346\214\207\345\215\227/\350\247\243\345\206\263\346\226\271\346\241\210/migration_solution.md" deleted file mode 100644 index 79839395b2da6748d4a08c67deb530ebd9e9f4cf..0000000000000000000000000000000000000000 --- "a/PRODUCT_DOCS/anolisos/23/\347\224\250\346\210\267\346\214\207\345\215\227/\350\247\243\345\206\263\346\226\271\346\241\210/migration_solution.md" +++ /dev/null @@ -1,67 +0,0 @@ -# CentOS停服替代场景的平滑迁移方案 - -tags: CentOS迁移, Anolis8 - -## 概述 - -操作系统迁移是一个复杂的工程，而在云原生时代，IaaS与PaaS的迁移复杂度更高，且相互影响。因而操作系统迁移不再是一个单机维度的OS切换，而是系统性的迁移工程。针对这一痛点，龙蜥社区在支持用户进行操作系统迁移的过程中，逐步狠点了一套行之有效的迁移方法论，并为CentOS用户提供了迁移到 Anolis OS 的迁移系统 AOMS(Anolis OS Migration System)。 - -## 场景挑战 - -随着各种虚拟化技术，开发语言的繁荣发展，在进行操作系统迁移时会出现多种开发语言，中间件，数据库，虚拟化手段混杂在一起的情况，而平台，业务，产品等不同纬度的诉求也会产生叠加。在这些场景下，操作系统迁移不再是一个单机维度的OS切换，而是需要从集群迁移视角来看待，做好全局评估与实施方案，做好灾备，灰度，回滚方案，并结合上层业务调度来进行迁移的系统工程。 - -## 方案特色 ws2ww2 -加点东西 -迁移方法论:评估，决策，实施，优化四步迁移法。 - -![迁移方法论(绿色标记)](../../../assets/solution/theory.png) - -迁移评估的5个维度及其关键的决策信息: - -![5个纬度(绿色标记)](../../../assets/solution/5_phases.png) - -迁移实施也是业务迁移实现平稳交付的关键环节，其阶段详细的流程要经过实施方案制定、基础设施准备、业务适配改造、迁移试点、迁移批量实施、割接护航6大步骤，确保迁移的交付环节可靠和高效。 - -## 实践验证 - -AOMS迁移方案包含如下三个场景: - -- CentOS 8迁移Anolis OS 8 -- CentOS 7迁移Anolis OS 7 -- CentOS 7迁移Anolis OS 8 - -### CentOS 8迁移Anolis OS 8及CentOS 7迁移Anolis OS 7场景 - -Anolis OS 8在做出差异性开发的同时，在生态上和依赖管理上保持与CentOS 8的兼容，AOMS充分利用了兼容的特性，提供了一键 式迁移工具 : `centos2anolis.py`。 - -CentOS 8迁移使用 Anolis release 相关的包替代 CentOS release ，通过 `yum distro-sync` 重装当前系统中所有的系统软件包。 软件重装的过程并不会修改当前系统基础配置，所以系统配置，业务配置，业务数据都不会被清除，迁移完成后这些数据无需重新设置。 - -使用迁移脚本前需要注意如下事项: - -- 迁移过程涉及到访问Anolis OS的官方repo ，需要确保待迁移环境网络能够正常访问Anolis OS repo。 -- 需要使用root用户执行，当前只支持CentOS 8系统的迁移，不支持CentOS stream系统迁移。 -- 迁移过程依赖于yum/dnf ，需要确保组件能够正常运行。 -- 迁移脚本提供了Anolis OS repo访问加速的功能，如果访问Anolis OS官方repo速度较慢，可以通过-s选项进行加速访问。 -- 迁移日志保存在/var/log/centos2anolis.log。 - -### CentOS 7迁移Anolis OS 8场景 - -CentOS 7到Anolis OS 8，无论是内核，基础软件包，工具链都发生了较大的变化。迁移工具需要考虑这些变化带来的兼容性问题。 AOMS提供的迁移工具leapp包含了迁移评估，迁移实施，配置还原等步骤，用于实现CentOS 7到Anolis OS 8的就地迁移 - -#### (一) 迁移评估 - -leapp扫描待迁移系统，搜集内核，软件包，系统配置基础信息，同时与目标系统( Anolis OS 8 )进行对比分析，对于不兼容项给 出影响分析和解决方案。 - -- 内核角度:给出Anolis OS 8中不再支持的内核特性，硬件驱动; -- 软件角度:给出系统命令的变更项，提示用户适配业务程序。 - -迁移评估报告会给出当前系统中所有可能影响到迁移的影响项目，当这些影响项目都被解决后，用户才能够继续做迁移实施。同时 业务程序可根据评估报告中的兼容性提示来适配迁移业务程序。 - -#### (二) 迁移实施 - -leapp首先搜集当前的系统信息，记录需要在重启后恢复的配置(如selinux状态)。迁移实施过程中，工具首先按照当前系统安装 的软件包列表，并根据CentOS 7到Anolis OS 8的软件包映射关系，从Anolis OS repo上提前下载迁移所需要的软件包，并基于 Anolis OS 8的软件包制作upgrade-initramfs ，在下一次重启后，系统自动进入 `upgrade-initramfs`，并触发所有软件包的就地升级。在所有的软件包就地升级完成后，自动重启进入系统配置还原阶段，待所有信息完成配置，系统重启进入新的OS ，完成OS的 就地迁移。 - - -## 总结 - -基于龙蜥社区AOMS迁移工具，用户可以解决由于CentOS停服带来的软件供应链风险，同时大大降低由于操作系统迁移带来的高技 术要求、高复杂操作的工程难度，帮助用户快速完成操作系统迁移。 diff --git "a/PRODUCT_DOCS/anolisos/23/\347\224\250\346\210\267\346\214\207\345\215\227/\350\247\243\345\206\263\346\226\271\346\241\210/\346\226\260\345\242\236\346\226\207\346\241\243.md" "b/PRODUCT_DOCS/anolisos/23/\347\224\250\346\210\267\346\214\207\345\215\227/\350\247\243\345\206\263\346\226\271\346\241\210/\346\226\260\345\242\236\346\226\207\346\241\243.md" deleted file mode 100644 index 8806fd7876f51006fd85322c42c317b574f93564..0000000000000000000000000000000000000000 --- "a/PRODUCT_DOCS/anolisos/23/\347\224\250\346\210\267\346\214\207\345\215\227/\350\247\243\345\206\263\346\226\271\346\241\210/\346\226\260\345\242\236\346\226\207\346\241\243.md" +++ /dev/null @@ -1,20 +0,0 @@ -新增文档.md - -## 二. 生命周期 -## 二. 生命周期 -## 二. 生命周期 -## 二. 生命周期 -## 二. 生命周期 -## 二. 生命周期 -加点东西 -## 二. 图片一 -![迁移方法论(绿色标记)](../../anolisos/23/用户指南/解决方案/641.jpg) - -## 三. 图片2 -![](../../anolisos/23/用户指南/解决方案/641.jpg) - -## 三. 图片2-1 -![]("../../anolisos/23/用户指南/解决方案/641.jpg") - -## 四. 图片3 -图片3 diff --git "a/PRODUCT_DOCS/anolisos/8.8/\345\217\221\350\241\214\350\257\264\346\230\216/CVE\346\274\217\346\264\236.md" "b/PRODUCT_DOCS/anolisos/8.8/\345\217\221\350\241\214\350\257\264\346\230\216/CVE\346\274\217\346\264\236.md" deleted file mode 100644 index 778e83af56fd338c14280c5edc3b466d66d59bc4..0000000000000000000000000000000000000000 --- "a/PRODUCT_DOCS/anolisos/8.8/\345\217\221\350\241\214\350\257\264\346\230\216/CVE\346\274\217\346\264\236.md" +++ /dev/null @@ -1,16 +0,0 @@ -漏洞漏洞漏洞 -漏洞漏洞漏洞 -漏洞漏洞漏洞 -漏洞漏洞漏洞 -漏洞漏洞漏洞 -漏洞漏洞漏洞 -漏洞漏洞漏洞 -漏洞漏洞漏洞 -漏洞漏洞漏洞 -漏洞漏洞漏洞 -漏洞漏洞漏洞 -漏洞漏洞漏洞 -漏洞漏洞漏洞 -漏洞漏洞漏洞 -漏洞漏洞漏洞 -## 二. 生命周期 \ No newline at end of file diff --git "a/PRODUCT_DOCS/anolisos/8.8/\345\217\221\350\241\214\350\257\264\346\230\216/\345\205\263\351\224\256\347\211\271\346\200\247.md" "b/PRODUCT_DOCS/anolisos/8.8/\345\217\221\350\241\214\350\257\264\346\230\216/\345\205\263\351\224\256\347\211\271\346\200\247.md" deleted file mode 100644 index 0b17de9a756bb57a1bc205e162dae2083c44ecfe..0000000000000000000000000000000000000000 --- "a/PRODUCT_DOCS/anolisos/8.8/\345\217\221\350\241\214\350\257\264\346\230\216/\345\205\263\351\224\256\347\211\271\346\200\247.md" +++ /dev/null @@ -1,13 +0,0 @@ -关键特性 -关键特性 -关键特性 -关键特性 -关键特性 -关键特性 -关键特性 -关键特性关键特性 -关键特性 -关键特性 -关键特性 -关键特性关键特性 -## 二. 生命周期 diff --git "a/PRODUCT_DOCS/anolisos/8.8/\345\217\221\350\241\214\350\257\264\346\230\216/\345\206\205\346\240\270\344\273\243\347\240\201\351\227\250\347\246\201\347\263\273\347\273\237\344\275\277\347\224\250\346\214\207\345\215\227.md" "b/PRODUCT_DOCS/anolisos/8.8/\345\217\221\350\241\214\350\257\264\346\230\216/\345\206\205\346\240\270\344\273\243\347\240\201\351\227\250\347\246\201\347\263\273\347\273\237\344\275\277\347\224\250\346\214\207\345\215\227.md" deleted file mode 100644 index e93644d38d6d43ff6522124138e2b3521d3adc05..0000000000000000000000000000000000000000 --- "a/PRODUCT_DOCS/anolisos/8.8/\345\217\221\350\241\214\350\257\264\346\230\216/\345\206\205\346\240\270\344\273\243\347\240\201\351\227\250\347\246\201\347\263\273\347\273\237\344\275\277\347\224\250\346\214\207\345\215\227.md" +++ /dev/null @@ -1,66 +0,0 @@ - -# 背景介绍 -龙蜥操作系统内核代码已经在Gitee上正式开源，与此同时，内核代码门禁系统也同步启用，并向社区开发者提供两种模式的代码检查，以保障龙蜥内核代码质量的稳定性和可靠性。更多内核代码开发流程，请参考[Cloud Kernel开发流程](https://gitee.com/anolis/cloud-kernel/wikis/Cloud%20Kernel%20%E5%BC%80%E5%8F%91%E6%B5%81%E7%A8%8B)。 - -# PR模式 -开发者fork内核代码仓库，并在本地进行开发，向内核代码仓库提交代码合入请求，即PR请求时，会自动触发代码门禁检查流程，并由社区机器人通过评论方式实时反馈流程进度，开发者可根据机器人的回复，在PR中评论相应的命令，以推进流程继续，直至通过评审和测试，最终合入内核代码仓库。 - -## CLA检查 -每当有新的PR提交时，代码门禁首先检查PR提交者的贡献者协议（CLA协议）签署情况，如果已签署，则会自动进入代码测试流程，并在PR中打上anolis_cla_pass，anolis_testing两个标签；如果未签署，则会在PR中打上anolis_cla_fail标签，并评论PR提示提交者未签署CLA协议。
当开发者签署CLA协议之后，可以在所提交的PR中评论/check-cla重新检查协议签署情况，如果通过，则会把anolis_cla_fail标签修改为anolis_cla_pass标签，并评论PR提示开发者后续操作；如果未签署，则会评论PR提示提交者未签署CLA协议。
评论/check-cla不会触发测试流程。 - -## 代码测试 -如果开发者已签署CLA协议，则在提交新的PR时自动触发代码测试流程，开发者可关注PR标签，存在anolis_testing则表示目前该PR正在进行代码测试，当测试完成之后，会把测试结果和详细结果链接一起评论到PR中，并根据测试结果修改anolis_testing标签，测试成功将标签修改为anolis_test_pass，测试失败将标签修改为anolis_test_fail。
开发者可以评论/retest重新进入代码测试流程，前提是CLA检查通过或者测试失败。同时，当机器人检测到PR中的代码发生了变化时，会重置当前测试状态，无论成功还是失败。如果在代码测试流程中更新了提交的代码，会增加code_update标签，当测试完成后，无论成功失败，本次测试结果均为失败。
maintainer可以评论/skip-test帮助开发者跳过某些可以忽略测试失败的场景。
目前线上测试机数量较少，且均为虚拟机，编译速度较慢，请开发者耐心等待。 - -## 自动合入 -当PR的测试通过时，即标签中存在anolis_test_pass时，需要maintainer对PR进行review，如果review不通过，需要开发者根据maintainer的提示修改代码，并重新触发测试，修改commit log和PR文本等不修改代码的行为，不需要重新触发测试。
当review通过之后，相关review的人员可以在评论中回复自己的RVB签名，由maintainer评论/merge进行自动何如。自动合入首先检查当前PR中的所有签名信息，按照规则进行排列，然后合入PR，在本地代码中更新，对新合入的代码进行签名添加和PR链接添加，上述流程全部成功之后，本次PR才算合入完成。 - -# 自助模式 -开发者fork内核代码仓库，并在本地进行开发，无需提交PR也可使用代码门禁的自助检测模式对已开发的代码进行检测，自助模式没有CLA检查和签名检查，仅触发代码测试流程，能够帮助开发者提前了解代码质量情况和问题。
使用社区帐号登录[CBC](https://cbc.openanolis.cn)，点击创建任务，首先选择fork仓库的源分支，然后将默认的代码仓库和代码分支修改为开发者自己的仓库和分支，其余选项可按照自身需求进行选择，最后点击确定即可进入代码测试流程，等待执行完毕，即可点击查看，跳转到任务详情页，查看详细的执行日志。
由于测试资源紧张，每位开发者仅允许创建两个执行的任务（一个x86一个arm，也可以两个x86任务），需等待之前提交的任务完成之后才能再次提交新的任务，每次检测提交的commit个数不能超过50个。 - -# 附录 - -## 命令说明 -| 回复命令 | 功能 | 可使用人员 | -| --- | --- | --- | -| /check-cla | 检查PR提交者签署CLA协议情况 | PR提交者，openanolis企业成员 | -| /retest | 重新进入代码测试流程 | PR提交者，openanolis企业成员 | -| /skip-test | 跳过代码测试流程 | maintainer | -| /merge | 进行代码合入 | maintainer | - - -## 标签说明 -| 标签 | 说明 | -| --- | --- | -| anolis_cla_pass | PR提交者已签署CLA协议 | -| anolis_cla_fail | PR提交者未签署CLA协议 | -| anolis_testing | 代码测试中 | -| code_update | 代码测试中发生了代码更新 | -| anolis_test_pass | 代码测试通过 | -| anolis_test_fail | 代码测试未通过 | -| anolis_merge_pass | 自动合入通过 | -| anolis_merge_fail | 自动合入未通过 | - - -## 检测说明 -| 检测项 | 检测目标 | 检测范围 | -| --- | --- | --- | -| review检测 | 检查每个commit log是否包含规范字段，例如#ANBZ等 | 每一个commit | -| checkpatch检测 | 与上游社区的checkpatch检测保持一致，范围根据情况有一定适配 | 每一个龙蜥自研的commit | -| build检测 | anolis_defconfig | 每一个commit，区分aarch64与x86_64 | -| kconfig检测 | 检测所有的config文件是否有新的config选项未设置，防止编译出错 | 只检测所有提交中的最后一个commit，区分aarch64与x86_64 | -| 全量build检测 | allnoconfig，allyesconfig，defconfig，anolis_defconfig，anolis-debug_defconfig | 只检测所有提交中的最后一个commit，区分aarch64与x86_64 | -| 启动检测 | 检测PR代码所构建出的内核rpm安装之后能否正常启动 | 只检测所有提交中的最后一个commit，区分aarch64与x86_64 | - - -## checkpatch规则 -| 包含anolis自研前缀 | 修改内核配置 | 来自upstream | 检查checkpatch | -| --- | --- | --- | --- | -| 是 | 是 | 是（warning提示） | 是 | -| 是 | 是 | 否 | 是 | -| 是 | 否 | 是（warning提示） | 是 | -| 是 | 否 | 否 | 是 | -| 否 | 是 | 是（warning提示） | 否 | -| 否 | 是 | 否 | 否 | -| 否 | 否 | 是 | 否 | -| 否 | 否 | 否（error报错） | 否 | - diff --git "a/PRODUCT_DOCS/anolisos/8.8/\345\217\221\350\241\214\350\257\264\346\230\216/\345\217\202\344\270\216\350\264\241\347\214\256.md" "b/PRODUCT_DOCS/anolisos/8.8/\345\217\221\350\241\214\350\257\264\346\230\216/\345\217\202\344\270\216\350\264\241\347\214\256.md" deleted file mode 100644 index 98e09197b10f07578c455f9c3df9a0484e456a16..0000000000000000000000000000000000000000 --- "a/PRODUCT_DOCS/anolisos/8.8/\345\217\221\350\241\214\350\257\264\346\230\216/\345\217\202\344\270\216\350\264\241\347\214\256.md" +++ /dev/null @@ -1,11 +0,0 @@ -参与贡献 -参与贡献 -参与贡献 -参与贡献 -参与贡献 -参与贡献 -参与贡献 -参与贡献 -参与贡献 -参与贡献 -## 二. 生命周期 \ No newline at end of file diff --git "a/PRODUCT_DOCS/anolisos/8.8/\345\217\221\350\241\214\350\257\264\346\230\216/\345\277\253\351\200\237\345\205\245\351\227\250.md" "b/PRODUCT_DOCS/anolisos/8.8/\345\217\221\350\241\214\350\257\264\346\230\216/\345\277\253\351\200\237\345\205\245\351\227\250.md" deleted file mode 100644 index 7bc487dbb7fa7b599eb48937add75bd611c2de7d..0000000000000000000000000000000000000000 --- "a/PRODUCT_DOCS/anolisos/8.8/\345\217\221\350\241\214\350\257\264\346\230\216/\345\277\253\351\200\237\345\205\245\351\227\250.md" +++ /dev/null @@ -1,8 +0,0 @@ -快速入门 -快速入门 -快速入门 -快速入门 -快速入门 -快速入门快速入门快速入门快速入门快速入门快速入门 -快速入门。 -## 二. 生命周期 \ No newline at end of file diff --git "a/PRODUCT_DOCS/anolisos/8.8/\345\217\221\350\241\214\350\257\264\346\230\216/\347\263\273\347\273\237\345\256\211\350\243\205.md" "b/PRODUCT_DOCS/anolisos/8.8/\345\217\221\350\241\214\350\257\264\346\230\216/\347\263\273\347\273\237\345\256\211\350\243\205.md" deleted file mode 100644 index bc706d2cd1d108765a6b9e43b522ffdb190614cb..0000000000000000000000000000000000000000 --- "a/PRODUCT_DOCS/anolisos/8.8/\345\217\221\350\241\214\350\257\264\346\230\216/\347\263\273\347\273\237\345\256\211\350\243\205.md" +++ /dev/null @@ -1,8 +0,0 @@ -系统安装系统安装系统安装系统安装系统安装系统安装 -系统安装系统安装系统安装系统安装系统安装 -系统安装系统安装系统安装 -系统安装系统安装 -系统安装系统安装 -系统安装系统安装 -系统安装系统安装系统安装； -## 二. 生命周期 \ No newline at end of file diff --git "a/PRODUCT_DOCS/anolisos/8.8/\345\217\221\350\241\214\350\257\264\346\230\216/\350\207\264\350\260\242.md" "b/PRODUCT_DOCS/anolisos/8.8/\345\217\221\350\241\214\350\257\264\346\230\216/\350\207\264\350\260\242.md" deleted file mode 100644 index e7de073eec1452c836161ee1ced487293fe23b50..0000000000000000000000000000000000000000 --- "a/PRODUCT_DOCS/anolisos/8.8/\345\217\221\350\241\214\350\257\264\346\230\216/\350\207\264\350\260\242.md" +++ /dev/null @@ -1,9 +0,0 @@ -致谢致谢致谢致谢致谢致谢 -致谢致谢致谢致谢致谢致谢 -致谢 -致谢 -致谢 -致谢 -致谢 -致谢 -## 二. 生命周期 diff --git "a/PRODUCT_DOCS/anolisos/8.8/\345\237\272\346\234\254\350\246\201\346\261\202/202301.md" "b/PRODUCT_DOCS/anolisos/8.8/\345\237\272\346\234\254\350\246\201\346\261\202/202301.md" deleted file mode 100644 index 8c4cee3de6bf828714b8245f5d5cd55589a8cb43..0000000000000000000000000000000000000000 --- "a/PRODUCT_DOCS/anolisos/8.8/\345\237\272\346\234\254\350\246\201\346\261\202/202301.md" +++ /dev/null @@ -1,47 +0,0 @@ -# 整体进展 - -- 发布 ANCK 5.10-013 版本。 -- 确定KABI机制整体方案。 -- 浪潮信息龙蜥联合实验室的工作事项更新。 - -# ANCK 5.10-013 版本 - -## 内核更新 - -- 版本更新至 5.10.134-13 -- 重要内核缺陷及安全漏洞(CVE)修复 -- 支持用户态/dev/ioasid -- SWIOTLB机制性能优化 -- virtio-net 打开 napi.tx 优化 TCP Small Queue 性能 -- 支持AST2600 PCIe 2D VGA Driver -- 支持FT2500处理器 -- 支持动态开启Group identity特性 -- arm64平台默认内核启动cmdline调整 -- 添加 Compact Numa Aware (CNA) spinlock 功能支持 -- 丰富arm64的perf mem和perf c2c功能 -- fsck.xfs 支持日志恢复 -- hugetext自适应按需大页 -- 支持SGX动态内存管理 -- 使能wireguard模块 - -## CVE修复列表 - -详情请参考： - -- [Anolis OS 7](https://anas.openanolis.cn/errata/detail/ANSA-2023:0002) -- [Anolis OS 8](https://anas.openanolis.cn/errata/detail/ANSA-2023:0001) - -## 二. 生命周期 -加点东西 -# 龙蜥社区第三方驱动 - -* 提供主流GPU在AnolisOS的Driver、CUDA、cuDNN安装测试与卸载指导文档：https://openanolis.cn/sig/AI_SIG/doc/721423765456666646 - -# 重要议题 - -- 调研并讨论了KABI机制的整体方案与实现细节。 -- 基于浪潮信息龙蜥联合实验室，讨论了关于整机硬件兼容性的相关事项，后续长期共建 AnolisOS 硬件兼容性标准和生态。 - -# 运营活动 - -- 无 diff --git "a/PRODUCT_DOCS/anolisos/test\351\207\215\345\244\215\347\233\256\345\275\225/test.md" "b/PRODUCT_DOCS/anolisos/test\351\207\215\345\244\215\347\233\256\345\275\225/test.md" deleted file mode 100644 index 0d8a2826449fe5350955cc71dca1eb42c0806c82..0000000000000000000000000000000000000000 --- "a/PRODUCT_DOCS/anolisos/test\351\207\215\345\244\215\347\233\256\345\275\225/test.md" +++ /dev/null @@ -1,2 +0,0 @@ -这是个测试文档 -

测试目录重复怎么展示 \ No newline at end of file diff --git a/PRODUCT_DOCS/assets/datop1.png b/PRODUCT_DOCS/assets/datop1.png deleted file mode 100644 index a798ff256c3f6abc0b1dfaa200bab76962adbb3b..0000000000000000000000000000000000000000 Binary files a/PRODUCT_DOCS/assets/datop1.png and /dev/null differ diff --git a/PRODUCT_DOCS/assets/datop2.png b/PRODUCT_DOCS/assets/datop2.png deleted file mode 100644 index bb5c5e8ec2ee954701e0c49a2b7209462b5fe610..0000000000000000000000000000000000000000 Binary files a/PRODUCT_DOCS/assets/datop2.png and /dev/null differ diff --git a/PRODUCT_DOCS/assets/datop3.png b/PRODUCT_DOCS/assets/datop3.png deleted file mode 100644 index f863b7c1a111f35db9fc16742807cbf611520b29..0000000000000000000000000000000000000000 Binary files a/PRODUCT_DOCS/assets/datop3.png and /dev/null differ diff --git a/PRODUCT_DOCS/maintainers.yaml b/PRODUCT_DOCS/maintainers.yaml deleted file mode 100644 index 2b7e089a26b1e484d235399e4a2a41116138640f..0000000000000000000000000000000000000000 --- a/PRODUCT_DOCS/maintainers.yaml +++ /dev/null @@ -1,20 +0,0 @@ -# 指定所有 maintainers -maintainers: - - default_group: &DG - - openanolis_id: hgj_admin - gitee_id: logic_jie - - network_group: &NG - - openanolis_id: suli0002 - gitee_id: suli01 - - openanolis_id: yankai - gitee_id: just-sososo - - openanolis_id: hahahaha - gitee_id: yutting123 - - other_group: &other_group - - openanolis_id: hahahaha - gitee_id: yutting123 -# 指定文档目录对应的用户组 -paths: - - /*: *DG - - ../test/*: *NG - - ../test1/*: *DG \ No newline at end of file diff --git a/PRODUCT_DOCS/menu.yaml b/PRODUCT_DOCS/menu.yaml deleted file mode 100644 index 7a3704915e5756cb5908c1fad08f463a56a14c66..0000000000000000000000000000000000000000 --- a/PRODUCT_DOCS/menu.yaml +++ /dev/null @@ -1,68 +0,0 @@ -PRODUCT_DOCS: - 测试文件: - 验证路径: - 阿斯顿发斯蒂芬: - 阿斯蒂芬撒地方撒地方撒打: - asdfsadfsad: ../test/test2.md - 验证文档绝对路径: /test/test1.md - 验证相对路径: ./test/1-HML用户指南说明.md - test3: ../test/test3.md - 全类型补充: ../test/test4.md - 全类型补充1: ../test/test4.md - anolisos: - '23': - 用户指南: - 解决方案: - LMP项目介绍: ../anolisos/23/用户指南/解决方案/LMP项目介绍.md - migration_solution: ../anolisos/23/用户指南/解决方案/migration_solution.md - 新增文档: ../anolisos/23/用户指南/解决方案/新增文档.md - '8.8': - 发行说明: - 快速入门: ../anolisos/8.8/发行说明/快速入门.md - 系统安装: ../anolisos/8.8/发行说明/系统安装.md - 关键特性: ../anolisos/8.8/发行说明/关键特性.md - CVE 漏洞: ../anolisos/8.8/发行说明/CVE漏洞.md - 源代码: ../anolisos/8.8/发行说明/源代码.md - 参与贡献: ../anolisos/8.8/发行说明/参与贡献.md - 致谢: ../anolisos/8.8/发行说明/致谢.md - 基本要求: - 要求: ../anolisos/8.8/基本要求/202301.md - 安装升级: - 安装指南: ../anolisos/8.8/发行说明/CVE漏洞.md - 升级指南: ../anolisos/8.8/发行说明/CVE漏洞.md - 系统管理: - 管理员指南: - 查看系统信息: ../anolisos/8.8/发行说明/CVE漏洞.md - 基础配置: ../anolisos/8.8/发行说明/CVE漏洞.md - 管理用户和用户组: ../anolisos/8.8/发行说明/CVE漏洞.md - 管理服务: ../anolisos/8.8/发行说明/CVE漏洞.md - 管理进程: ../anolisos/8.8/发行说明/CVE漏洞.md - 管理内存: ../anolisos/8.8/发行说明/CVE漏洞.md - 管理网络: ../anolisos/8.8/发行说明/CVE漏洞.md - 运维指南: - 运维概述: ../anolisos/8.8/发行说明/致谢.md - 系统资源与性能: ../anolisos/8.8/发行说明/致谢.md - 信息收集: ../anolisos/8.8/发行说明/致谢.md - 故障应急处理: ../anolisos/8.8/发行说明/致谢.md - 常用工具: ../anolisos/8.8/发行说明/致谢.md - 常用技能: ../anolisos/8.8/发行说明/致谢.md - 网络: ../anolisos/23/用户指南/解决方案/migration_solution.md - 维护: ../anolisos/23/用户指南/解决方案/migration_solution.md - 安全: - 签名: ../anolisos/8.8/发行说明/致谢.md - 安全加固: ../anolisos/8.8/发行说明/致谢.md - SBOM: ../anolisos/8.8/基本要求/202301.md - 云原生: ../anolisos/8.8/基本要求/202301.md - 桌面: ../anolisos/8.8/基本要求/202301.md - 嵌入式: ../anolisos/8.8/基本要求/202301.md - 虚拟化: ../anolisos/8.8/基本要求/202301.md - 边缘计算: ../anolisos/8.8/基本要求/202301.md - zhongjietest: - testa目录: - w重复目录: ../anolisos/test重复目录/test.md - 2边缘计算: ../anolisos/8.8/基本要求/202301.md - zhongjietest2: - 一级目录: - 二级目录: - 三级目录: - 4级文件:../anolisos/test重复目录/test.md \ No newline at end of file diff --git "a/PRODUCT_DOCS/test/1-HML\347\224\250\346\210\267\346\214\207\345\215\227\350\257\264\346\230\216.md" "b/PRODUCT_DOCS/test/1-HML\347\224\250\346\210\267\346\214\207\345\215\227\350\257\264\346\230\216.md" deleted file mode 100644 index 497e8eb98e4a0f4aaaecd8b3e0c41e17a9f6c4ad..0000000000000000000000000000000000000000 --- "a/PRODUCT_DOCS/test/1-HML\347\224\250\346\210\267\346\214\207\345\215\227\350\257\264\346\230\216.md" +++ /dev/null @@ -1,123 +0,0 @@ -## HML - -### 简介 - -HML是基于海光CPU平台构建一套高性能的数学函数库，基于海光CPU架构特点极致优化，能够充分发挥海光CPU计算性能。 - -官方发布的 HML数学库位于 gitee 的 `hygon-devkit` 仓库，地址： - -```sh -git clone https://gitee.com/anolis/hygon-devkit.git -``` - -HML高性能数学库在hygon-devkit中的目录结构示意图如下： - -``` -hygon-devkit/ - ├─ hml - ├──pkg - │ └── hml_1.0.0 - │ - └── README.md - -``` - -* pkg目录：内含各版本hml高性能数学库。 -* README.md文件：有关HML的简单情况。 - - -### 安装与使用 - -#### 环境配置 - -确保gcc版本号>=8.5.0 -```sh -可以通过如下命令查看gcc版本号 -gcc -v -``` - -#### 安装 - -* 安装包命令规则 - -包命名规则如下： -hml----.. -如： -hml-1.0.0-2024-0320-rc.x86_64.rpm - -* RPM安装 -```sh -# 1. 安装 - sudo rpm -Uvh hml-1.0.0-2024-0320-rc.x86_64.rpm - -# 2. 检查是否安装成功 - rpm -qi hml - -# 3. 显示安装路径 - rpm -ql hml - -# 4. 卸载 - sudo rpm --verbose --erase hml -``` - -* DEB安装 -```sh -# 1. 检查DEB信息 - dpkg -I hml-1.0.0-2024-0320-rc.x86_64.deb - -# 2. 安装 - sudo dpkg -i hml-1.0.0-2024-0320-rc.x86_64.deb - -# 3. 检查安装是否成功 - dpkg -l hml - -# 4. 卸载 - sudo dpkg -r hml -``` - -* 安装路径 - HML库会被安装到/opt/hygon/目录下，包含blas、fft、smm、sparse、vml、vsip库。 - -#### 使用 - -* 添加HML库路径到环境变量 -```sh - export LD_LIBRARY_PATH=/opt/hygon:$LD_LIBRARY_PATH -``` - -* 链接HML库 -```sh -# 1. 链接BLAS库 - -L /opt/hygon/blas/lib -lblis-hg - -# 2. 链接FFT库 - -L /opt/hygon/fft/fftw_double/lib -lfftw3 - -L /opt/hygon/fft/fftw_single/lib -lfftw3 - -# 3. 链接SMM库 - -L /opt/hygon/smm/lib -lsmm-hg - -# 4. 链接SPARSE库 - -L /opt/hygon/sparse/lib -lhml_sparse-hg - -# 5. 链接VML库 - -L /opt/hygon/vml/lib -lvml-hg - -# 6. 链接VSIP库 - -L /opt/hygon/vsip/lib -lvsip-hg -``` - -### 使用指南 - -参考HML用户指南.pdf(https://gitee.com/anolis/hygon-devkit/blob/master/hml/HML%E7%94%A8%E6%88%B7%E6%8C%87%E5%8D%97.pdf) - -指南包含： - -* HML库介绍 -* HML库安装 -* HML_BLAS库接口和使用说明以及代码示例。 -* HML_SMM库接口和使用说明以及代码示例。 -* HML_SPARSE接口和使用说明以及代码示例。 -* HML_VML接口和使用说明以及代码示例。 -* HML_VSIP接口和使用说明以及代码示例。 - diff --git a/PRODUCT_DOCS/test/test1.md b/PRODUCT_DOCS/test/test1.md deleted file mode 100644 index feb8ed9f73e434a0791a0c82801610854dd1e3af..0000000000000000000000000000000000000000 --- a/PRODUCT_DOCS/test/test1.md +++ /dev/null @@ -1,966 +0,0 @@ -# Anolis OS Cloud Kernel: RAS White Paper - -## REVISION HISTORY - -| DATE | VERSION | DESCRIPTION | AUTHOR | APPROVER | -| ---------- | ------- | --------------- | ----------------------- | ----------- | -| 2022/12/31 | 1.0 | Initial version | Shuai Xue, Ruidong Tian | Baolin Wang | - -## Terms and Abbreviations - - -## Abstract - -Reliability, availability and serviceability (RAS) is a computer hardware engineering term referring to the elimination of hardware failures to ensure maximum system uptime. - -This document describes the memory RAS features in detail, explaining how server availability is enhanced with the memory RAS features on Yitian 710 servers running Anolis OS Cloud Kernel. - -## Introduction - -The server is one of the key components of any modern data center infrastructure. It consists of a variety of hardware parts, including processors, storage devices, PCIe devices, power supplies, and fans. - -In today’s hyper scale Cloud Data centers, correct server operation and data integrity are critical to ensure service continuity. In other words, we must avoid data corruption no matter data is stored in any server component (memory, cache, or processor registers) or transmitted through any platform links (Intel®UPI, PCI Express, or DMI). - -Server reliability, availability, and serviceability (RAS) are crucial issues for modern enterprise IT shops that deliver mission-critical applications and services, as application delivery failures can be extremely costly per hour of system downtime. Although hardware failures are rare, they are inevitable but random events, especially for large scale data centers. If such incidents are not efficiently diagnosed, the consequences may be very serious and sometimes even catastrophic, such as data corruption or server crash. which are top concerns to meet SLAs (Service Level Agreement) for cloud end users. The likelihood of such failures increases statistically with the size of the servers, data, and memory required for these deployments. Furthermore, considering today’s server system with more and more CPU cores shipped on hundreds of Virtual Machines (VM) and DDR DIMMs operating on it, the impact of server crash caused by hardware failures is much bigger than before. - -Modern CPU offers an extensive and robust set of RAS features in silicon to provide error detection, correction, containment, and recovery in all processors, memory, and I/O data paths based on Intel Machine Check Architecture (MCA) Recovery mechanism or ARM v8.2 RAS Extension. When a server component fails, OS with such RAS features is capable of recovery from hardware error, maximizing service availability and maintaining data integrity. - -## RAS Mechanism Overview - -### Error categories - -One of the most popular RAS schemes used in the memory subsystem is Error Correction Code (ECC) SECDED (Single-bit Error Correction and Double-bit Error Detection), which as its name indicates, the DDR controller can correct single-bit errors and detect double-bit errors on the received data from the DRAMs. - -Talking about detected hardware errors, we can classify memory errors as either corrected errors (CE) or uncorrected errors (UCE). - -- **Correctable Error (CE)** - the hardware error detection mechanism detected and automatically corrected the error. -- **Uncorrected errors (UCE)** - are severe enough, hardware detect - -![MCtest 2.png](../assets/datop1.png) - -Typically, uncorrectable errors further fall into three categories: - -- **Uncorrected Recoverable Errors (UCR)** - are uncorrected errors that have been detected and signaled but have not corrupted the processor context. For certain UCR errors, this means that once system software has performed a certain recovery action, it is possible to continue execution on this processor. UCR error reporting provides an error containment mechanism for data poisoning. It can be further divided into: - - **Action Required (AR)**: The error occurs in execution context. If such an error is detected, and the memory access has been architecturally executed, that error is considered “consumed”. CPU will signal a synchronous exception when an error is detected and the processor already consumes the memory. OS requires to take action (for example, offline failure page/kill failure thread) to recover this uncorrectable error. - - **Action Optional (AO)**: The error is detected out of processor execution context, e.g. when detected by a background scrubber or accessed by prefetch instruction. In this scenario, the data in the memory are corrupted, but OS is optional to take action to recover this uncorrectable error. -- **Uncorrected Error (UC)** - 2 bit (uncorrectable) error occurs and can not be corrected by hardware. The processor context is corrupted and cannot continue to operate the system. OS requires to panic immediately. - -OS will take specific actions based on the above failures. Handling CEs is done in silicon, e.g. using ECCs and can be made transparent to system. Handling DUEs, however, can require collaboration from higher layers in the hardware-software stack, from silicon to virtual memory manager, to the operating system (OS), and sometimes even the application layer. - -### X86 MCA Recovery - -The new Intel Xeon Scalable Family processors support recovery from some memory errors based on the Machine Check Architecture (MCA) Recovery mechanism. The figure shows a basic workflow with legacy MCA or EMCA. - -Prior to enhanced machine check architecture (EMCA), IA32-legacy version of Machine Check Architecture (MCA) implemented error handling where all the errors were logged in architected registers (MC banks) and signaled to OS/hypervisor. CMCI is signaled only when CE is over threshold and OS CMCI handler, aka, `threshold_interrupt` read MC Banks and other HW registers for further error handling. MCE is signaled when uncorrected or fatal errors are detected and its handler `do_machine_check` will poison the page and then kill current thread in memory failure. - -EMCA enables BIOS-based recovery from errors which redirects MCE and CMCI to firmware first (via SMI) before sending it to the OS error handler. It allows firmware first to handle, collect, and build enhanced error logs then report to system software. - -![ras_x86.png](../assets/datop1.png) - -### ARM v8.2 RAS Extension - -The RAS Extension is a mandatory extension to the Armv8.2 architecture, and it is an optional extension to the Armv8.0 and Armv8.1 architectures. The figure shows a basic workflow with Firmware First mode. -![m1_ras_flow.png](../assets/datop2.png) - -- Prerequisite: System boot and init - - - Platform RAS driver init: BL31 initializes SPM (includes MM dispatcher) and SDEI dispatcher, UEFI query and update error source info in HEST - - OS RAS driver init: HEST driver scans HEST table and registers error handlers by APEI notification, e.g. SDEI, SEA, GPIO, etc. - -1. RAS event (UE or CE) occurred, the event will be routed to EL3 (SPM). -2. SPM routes the event to RAS error handler in S-EL0 (MM Foundation). -3. MM Foundation creates the CPER blobs by the info from RAS Extension. -4. SPM notifies RAS event through APEI notification, e.g. SDEI, SEA, etc. to call the corresponding OS registered handler. -5. OS gets the CPER blobs by Error Status Address block, processes the error, and tries to recover. -6. OS reports the error event by RAS tracepoints. -7. rasdaemon log error info from RAS event to recorder. - -For example, the platform specifies SDEI as an APEI notification to handle RAS events. As part of initialization, the kernel registers a handler for a platform event, enables the event, and unmasks the current PE. At a later point in time, a critical event, e.g. DDR UE interrupt is trapped into EL3. EL3 performs a first-level triage of the event, and a RAS component assumes further handling. The dispatch completes, but intends to involve Non-secure world UEFI in further handling, and therefore decides to explicitly dispatch an event (which the kernel had already registered for). - -## RAS Solution on ANCK - -Modern CPU offers an extensive and robust set of RAS features in silicon to provide error detection, correction, containment, and recovery in all processors, memory, and I/O data paths based on Intel Machine Check Architecture (MCA) Recovery mechanism or ARM v8.2 RAS Extension. The RAS mechanism is intended to assist CPU designers and CPU debuggers in diagnosing, isolating, and understanding processor failures. It is also intended to help system administrators detect transient and age-related failures, suffered during long-term operation of the server. - -To reduce systems downtime, the OS recovery process for ensuring reliable hardware performance is to detect and correct errors where possible, recover from uncorrectable errors through either physical or logical replacement of a failing component or data path, and prevent future errors by replacing in timely fashion components most likely to fail. - -The figure shows the system error handling flow with Anolis OS. - -![RAS_OS_Error_Flow.png](../assets/datop3.png) - -### Memory Failure Recovery - -The RAS mechanism is used to detect, signal, and record machine fault information. Some of these faults are correctable, whereas others are uncorrectable. The Memory Failure Recovery capabilities of RAS mechanism allow systems to continue to operate when an uncorrected error is detected in the system. If not for these capabilities, the system would crash and might require hardware replacement or a system reboot. - -When an uncorrectable error is detected on a requested memory address, data poisoning is used to inform the CPU that the data requested has an uncorrectable error. When the hardware detects an uncorrectable memory error, it routes a poison bit along with the data to the CPU. For the Intel architecture, when the CPU detects this poison bit, it sends a processor interrupt signal to the operating system to notify it of this error. The operating system can then examine the uncorrectable memory error, determine if the software can recover, and perform recovery actions via an interrupt handler. - -Memory Failure Recovery handles UCR errors including: - -- AR are synchronous Errors. There are two types of such errors signaled as data abort or instruction abort. For example, data abort is detected by Data Cache Unit (DCU) and instruction abort is detected by Instruction Fetch Unit (IFU) which are both signaled as Machine Check Exception. The analogy exception is Synchronous External Abort in Arm64 platform. - -- AO are asynchronous Errors. Such errors are detected by memory patrol scrub, prefetch, Last Level Cache (LLC) explicit writeback transaction for X86 platform or store less than ECC protection granularity, e.g. per 64 bit on Neoverse N1 and N2. - -The kernel will attempt to hard-offline the page, by trying to unmap the page or killing any owner, or triggering IO errors if needed. This may kill any processes accessing the page. The kernel will avoid to access this page assuming it's poisoned by the hardware. -Let's dive into more details about Anolis OS Cloud Kernel running on Severs capable of Intel MCA Recovery or ARM v8.2 RAS Extension. - -#### User Space Action Required Recovery - -In Linux, user memory and kernel memory are independent and implemented in separate address spaces. The address spaces are virtualized, meaning that the addresses are abstracted from physical memory (through a process detailed shortly). In fact, the kernel itself resides in one address space, and each process resides in its own address space, so each process can be isolated completely and protected by the paging mechanism. These address spaces consist of virtual memory addresses, permitting many processes with independent address spaces to refer to a considerably smaller physical address space (the physical memory in the machine). Not only is this convenient, but it's also secure, because each address space is independent and isolated and therefore secure. One isolated address space per process is the basis of preventing the fault from being propagated to the enclosing scope or process. - -Without OS memory failure recovery and hardware data poisoning support, once a process is consuming poison, it will be regarded as a fatal event and the kernel will crash immediately. When the OS kernel receives the UCE events, the `memory_failure` function (HWPoison handler) analyzes the log to verify if recovery is feasible. It then takes actions to offline the affected memory page and logs the event in the -mcelog or RAS tracepoint, and the possible results of the actions appear to be ignoring, recovery, delay, and failure. - -The HWPoison handler starts the recovery action by isolating the affected page and declaring it with a “poisoned” tag to disallow any reuse of the page. In the case of an AR-instruction abort event, the HWPoison handler then reloads the 4KB page containing the instruction to a new physical page and resumes normal operation. In the case of an AR-data abort event, the HWPoison handler triggers a “SIGBUS” event to take further recovery action by notifying only the accessing process or any owner process which is configured by hwpoison-aware technique like prctl or early kill. The application has a choice to either reload the data and resume normal execution, or terminate the application to avoid crashing the entire system. - - - -#### Kernel Space Action Required Recovery - -The kernel itself resides in one address space, and contains a process scheduler, networking stack, virtual file system, and device drivers for hardware support, to name just a few, shared by all user space processes. When a user space application requires the services provided by the kernel, it will signal the kernel to execute a syscall, and switch to kernel mode for the duration of the syscall execution. In principle, if any UCE error was triggered while executing OS kernel code, then the UCE error will be fatal. -Kernel also provides user space memory access APIs for cross-space data movement from or to user memory. Cross-space data movements are limited to perform in Linux by special functions, defined in ``. Such a movement is either performed by a generic (memcpy-like) function or by functions optimized for a specific data size (char, short, int, long); The role of the data-movement functions is shown in following figure as it relates to the types involved for copy (simple vs. aggregate), note, not all user access API is showed. - - -For example, when a user process tries to write a buffer to a file, kernel will copy the data from userspace and then write them to disk. If a UCE error occurs in the userspace buffer, kernel will consume the poison data while copying data from userspace. In such case, a system wide reboot is not unnecessary. The point behind Kernel Space Action Required Recovery is that the poison data manipulated by kernel is owned by the user process. If the application that initiated the copy and owned corrupt data can be easily identified by the kernel, it is possible to isolate the corrupt data by marking the affected page with the ‘poison’ tag and terminating the initiator/impacted applications to stop the corrupt data from spreading. - -The mechanism is to track uaccess in extable in advance and change pc to fixup handler while handling synchronous Errors. Then the uaccess will jump to fixup handler which then endups the uaccess process. If the exception is fixuped correctly, the kernel can avoid panic. In the copy from user case, e.g. initiated by write(2), it is not even necessary to send a SIGBUS. System calls should return -EFAULT or a short count for write(2). The Figure shows the basic workflow for Arm64 platform and the implementation of the X86 platform is similar. - - -#### Action Optional Recovery: Patrol Scrub - -ECC Patrol Scrubber is a common block in DDR Controller (DDRC) capable of generating initialization write commands, periodic read commands, periodic RMW commands, and correction RMW commands. It proactively searches the system memory, repairing correctable errors. Periodic scrubbing is performed by the ECC Patrol Scrubber to prevent the accumulation of single-bit errors and increase the reliability of the system by correcting single-bit ECC errors in time, before they turn into uncorrectable 2-bit errors. -When an uncorrectable 2-bit error is detected by Patrol Scrubber, an interrupt will be signaled. In such case, kernel will just unmap the poisoned page because no process is accessing the poison data by default. - -On X86 old generation platform, after the patrol scrub detects memory uncorrected data errors, it will report the OS by MCE. The new generation like Intel® Xeon® Processor-based platforms have an `UCE_TO_CE_DOWNGRAGE` mode where the users can request the memory controller to report UCE found by the patrol scrubber as a corrected type. It is also called ‘downgrading patrol scrub CE/SRAO to CE’. Those errors are signaled by using CMCI, a process less disruptive than a machine check and thus helps avoid double MCE interrupts to crash the system. We recommend setting it on. - -![scrub_recovery](../../assets/Scrub_Recovery.png) - -#### Action Optional Recovery: Prefetch - -Many modern processors implement implicit hardware prefetching and support software prefetching. With software prefetching the programmer or compiler inserts prefetch instructions into the program. For example, Prefetch from Memory (`PRFM`) enables code to provide a hint to the memory system that data from a particular address will be used by the program soon. While for implicit hardware prefetching, the processor monitors the memory access pattern of the running program and tries to predict what data the program will access next and prefetches that data. - -If a prefetch request accesses to poison data, an asynchronous error will be detected and an interrupt will be signaled, e.g. CMCI on Intel Icelake and SPI on Yitian 710. In such case, kernel will just unmap the poison page like Patrol Scrub error. - -Another prefetch scenario we observed is that the poisoned page may still be accessed even though all its owned user processes are killed. After a page is poisoned, it will never be reused, e.g. reallocated to other processes. The problem is that the poisoned page is only unmapped from the page table of user-space process, the kernel page table of the linear mapping range is not considered. It requires dynamically splitting the target linear mapping into PTE granularity and then clearing the PTE valid attribute of the related virtual address while processing memory failure. As a result, the poisoned page will be marked as not-present, which avoids speculative and prefetch access. - -#### Action Optional Recovery: Store - -Write is another type of request which may read the poison data from DDR controller. On Yitian 710, L2 cache is protected by a per 64-bit ECC scheme, a write less than 64bit will trigger asynchronous External Aborts, signaled as SErrors. Similarly, an asynchronous interrupt CMCI is signaled on X86 platform. In such case, it requires firmware to take extra care that does not notify kernel as a fatal error to avoid a system wide reboot. - -Unlike read access, write access does not cause error propagation. When such an error is detected, kernel will regard it as AO asynchronous error and only unmap the poisoned page. However, the write did not take effect, resulting in data loss. A subsequent 64-bit write access has the opportunity to correct this error. When the process trie to consume the poisoned page, the HWPoison handler triggers a “SIGBUS” event to take further recovery action by notifying only the accessing process or any owner process which is configured by hwpoison-aware technique like prctl or early kill. - -#### HWPoison-aware Strategy - -There are in principle two hwpoison-aware strategies to kill processes on poison: - -- just unmap the data and wait for an actual reference before killing -- kill all processes that have the corrupted and not reloadable page mapped as soon as the corruption is detected. - -Both have advantages and disadvantages and should be used in different situations. **Right now both are implemented and can be switched** with a new sysctl vm.memory_failure_early_kill. The default is late kill. Applications can override this setting individually with the PR_MCE_KILL prctl. For example, if early kill is set by `sysctl -w vm.memory_failure_early_kill=1`, kernel will kill any process which mapped the poison page when an uncorrectable 2-bit error is detected by Patrol Scrubber. - -Note, the kill is done using a catchable SIGBUS with BUS_MCEERR_AO, so processes can handle this if they want to. While for AR synchronous errors, the kill is done using a catchable SIGBUS with BUS_MCEERR_AR. - -### Memory Predictive Failure Analysis with Rasdeamon - -When a 1-bit error is detected, it is transparently corrected by the hardware ECC mechanism, and internal counters are updated. If a correctable fault occurs in the memory, we don't need to perform any recovery action on the OS. However, if we continue to see correctable errors, then perhaps the memory is failing. To avoid the possibility of future uncorrectable faults on the same page, we can copy the data to a different page and mark the page as offline. This is the mechanism used by Memory Predictive Failure Analysis (PFA). - -The PFA is powered by the userspace rasdaemon package. Rasdaemon written by Mauro Carvalho Chehab is one of the tools to gather MCE information. Previously, the task was performed by the mcelog package. However, the driver it depends on has been deprecated after kernel 4.12, we recommend switching to the new generation rasdaemon solution. - -If a memory error is detected and signaled, the OS related handler reports them to userspace through RAS tracepoints with EDAC decoded DIMM statistics for accounting and predictive failure analysis. Rasdeamon runs as a daemon that monitors the platform RAS reports from the Linux kernel trace events. And it optionally records RAS events via Sqlite3 which has the benefit of keeping a persistent record of the RAS events. Based on statistical results, some actions can be configured and taken to prevent corrected errors from evoluting into uncorrected errors. For example, specify soft offline action or hard offline action when exceeding a page error threshold within refresh cycles, e.g. 50 CEs perf 24 hours. When a soft action is specified, the kernel will then attempt to soft-offline it, by moving the contents elsewhere or dropping it if possible. The kernel will then be placed on the bad page list and never be reused. The page is still accessible, not poisoned. The kernel will never kill anything for this, but rather fail the offline. - -Note, the RAS feature is only covered but not limited to memory, the processor, PCIe, and Platform(e.g. CMN, GIC, SMMU, etc) RAS are also supported on Anolis OS Cloud Kernel. - -## RAS Validation Guide - -EINJ provides a hardware error injection mechanism. It is very useful for debugging and testing APEI and RAS features in general. In this white paper, we take Yitian 710 running Anolis OS as an example. Note that this guide is also suitable for other platforms with advanced RAS features. - -### Prerequisite - -#### BIOS Requirement - -You need to check whether your BIOS supports EINJ first. For Panjiu M Series equipped with Yitian 710, make ensure to set the following configuration properly. - -```bash -[Platform Configuration][Processor Configuration][CPU Poison] -[Platform Configuration][Memory RAS Configuration][Poison] -[Platform Configuration][Memory RAS Configuration][CE threshold ]<0> -[Platform Configuration][Memory RAS Configuration][Ecc] -[Platform Configuration][PCI-E Configuration][PCIe RAS Support] -[Platform Configuration][PCI-E Configuration][AER CE] -[Platform Configuration][Advance Configuration][Global RAS Enable] -[Platform Configuration][Advance Configuration][EINJ Enable] -[Platform Configuration][Advance Configuration][Route EA to El3] -``` - -#### OS Requirement - -Then, you need to check whether your BIOS supports EINJ. For that, look for early boot messages similar to this one, e.g. on Yitian 710 : - -```bash -#dmesg | grep EINJ -[ 0.000000] ACPI: EINJ 0x00000000F8FAFE18 000150 (v01 PTG PTG01 00000000 PTG 20200717) -``` - -which shows that the BIOS is exposing an EINJ table - it is the mechanism through which the injection is done. - -By default, the EINJ driver is built-in on Anolis OS. If you build kernel from scratch, make sure the following are options enabled in your kernel configuration: - -```shell -CONFIG_DEBUG_FS -CONFIG_ACPI_APEI -CONFIG_ACPI_APEI_EINJ -``` - -Check if the einj module is loaded: - -```shell -$ lsmod | grep einj -einj 16384 0 -``` - -If not, load the einj modules by yourself - -```shell -modprobe einj -``` - -### EINJ Interface - -The EINJ user interface is in \/apei/einj, by default, `/sys/kernel/debug/apei/einj`. - -```bash -#ls /sys/kernel/debug/apei/einj/ -available_error_type error_inject error_type flags notrigger param1 param2 param3 param4 vendor vendor_flags -``` - -The standard error types for the EINJ interface include Processor, Memory, PCIe, and Platform. The file `available_error_type`displays the supported standard error types and their severities, e.g. - -```bash -#cat /sys/kernel/debug/apei/einj/available_error_type -0x00000001 Processor Correctable -0x00000002 Processor Uncorrectable non-fatal -0x00000004 Processor Uncorrectable fatal -0x00000008 Memory Correctable -0x00000010 Memory Uncorrectable non-fatal -0x00000020 Memory Uncorrectable fatal -0x00000040 PCI Express Correctable -0x00000080 PCI Express Uncorrectable non-fatal -0x00000100 PCI Express Uncorrectable fatal -0x00000200 Platform Correctable -0x00000400 Platform Uncorrectable non-fatal -0x00000800 Platform Uncorrectable fatal -``` - -The error injection mechanism is a two-step process. - -- First select an error specified all necessary error parameters including`error_type`,`flags`,`param{1-4}`and `notrigger`，then write any integer to `error_inject` to inject the error. -- The second step performs some actions to trigger it. Setting `notrigger` to 1 skips the trigger phase, which may allow the user to cause the error in some other context by a simple access to the CPU, memory location, or device that is the target of the error injection. Setting `notrigger` to 0, the BIOS should trigger the error internally, e.g. by kicking the patrol scrubber. Whether this actually works depends on what operations the BIOS actually includes in the trigger phase. - -Please refer to the kernel document for more details about EINJ user interface format. - -#### Error Injection Examples with APEI Debugfs - -In this section, we show examples to inject errors with APEI Debugfs on Yitian 710. - -##### Processor Uncorrectable non-fatal - -```bash -APEI_IF=/sys/kernel/debug/apei/einj -echo 33 > $APEI_IF/param3 # APIC ID -echo 0x1 > $APEI_IF/flags -echo 0x00000002 > $APEI_IF/error_type -echo 1 > $APEI_IF/error_inject -``` - -The dmesg log: - -```bash -[ 1820.578688] {3}[Hardware Error]: Hardware error from APEI Generic Hardware Error Source: 4 -[ 1820.589434] {3}[Hardware Error]: event severity: recoverable -[ 1820.595078] {3}[Hardware Error]: precise tstamp: 2023-01-02 17:23:02 -[ 1820.601503] {3}[Hardware Error]: Error 0, type: recoverable -[ 1820.607147] {3}[Hardware Error]: section_type: ARM processor error -[ 1820.613485] {3}[Hardware Error]: MIDR: 0x00000000410fd490 -[ 1820.619041] {3}[Hardware Error]: Multiprocessor Affinity Register (MPIDR): 0x0000000081210000 -[ 1820.627723] {3}[Hardware Error]: running state: 0x1 -[ 1820.632759] {3}[Hardware Error]: Power State Coordination Interface state: 0 -[ 1820.639965] {3}[Hardware Error]: Error info structure 0: -[ 1820.645435] {3}[Hardware Error]: num errors: 1 -[ 1820.650037] {3}[Hardware Error]: error_type: 0, cache error -[ 1820.655854] {3}[Hardware Error]: error_info: 0x0000000000800015 -[ 1820.662019] {3}[Hardware Error]: transaction type: Instruction -[ 1820.668183] {3}[Hardware Error]: cache level: 2 -[ 1820.673045] {3}[Hardware Error]: the error has not been corrected -[ 1820.679470] {3}[Hardware Error]: type: CORE (0x41), ras_count:1 -[ 1820.685461] {3}[Hardware Error]: sub_type: 0x0 -[ 1820.689977] {3}[Hardware Error]: fr: 0x10a9a2, ctrl: 0x0, status: 0x44800007, addr: 0x800e9f716acea53d -[ 1820.699352] {3}[Hardware Error]: misc0: 0x4, misc1: 0x0, misc2: 0x0, misc3: 0x0 -``` - -##### Processor Uncorrectable fatal - -Script to inject and trigger processor uncorrectable fatal error. Note, a fatal error will cause the kernel to panic. - -```bash -APEI_IF=/sys/kernel/debug/apei/einj -echo 33 > $APEI_IF/param3 # APIC ID -echo 0x1 > $APEI_IF/flags -echo 0x00000004 > $APEI_IF/error_type -echo 1 > $APEI_IF/error_inject -``` - -The dmesg log: - -```bash -[10862.838686] {10}[Hardware Error]: Hardware error from APEI Generic Hardware Error Source: 3 -[10862.838687] {10}[Hardware Error]: event severity: fatal -[10862.838688] {10}[Hardware Error]: precise tstamp: 2023-01-02 19:53:43 -[10862.838688] {10}[Hardware Error]: Error 0, type: fatal -[10862.838688] {10}[Hardware Error]: section_type: ARM processor error -[10862.838689] {10}[Hardware Error]: MIDR: 0x00000000410fd490 -[10862.838689] {10}[Hardware Error]: Multiprocessor Affinity Register (MPIDR): 0x0000000081210000 -[10862.838689] {10}[Hardware Error]: running state: 0x1 -[10862.838690] {10}[Hardware Error]: Power State Coordination Interface state: 0 -[10862.838690] {10}[Hardware Error]: Error info structure 0: -[10862.838691] {10}[Hardware Error]: num errors: 1 -[10862.838691] {10}[Hardware Error]: error_type: 0, cache error -[10862.838691] {10}[Hardware Error]: error_info: 0x0000000000800015 -[10862.838692] {10}[Hardware Error]: transaction type: Instruction -[10862.838692] {10}[Hardware Error]: cache level: 2 -[10862.838693] {10}[Hardware Error]: the error has not been corrected -[10862.838693] {10}[Hardware Error]: type: CORE (0x41), ras_count:1 -[10862.838693] {10}[Hardware Error]: sub_type: 0x0 -[10862.838694] {10}[Hardware Error]: fr: 0x10a9a2, ctrl: 0x0, status: 0x74000007, addr: 0x800e9f716acea53d -[10862.838694] {10}[Hardware Error]: misc0: 0x4, misc1: 0x0, misc2: 0x0, misc3: 0x0 -[10862.838695] Kernel panic - not syncing: Fatal hardware error! -``` - -#### Memory - -##### Correctable - -Firstly, run a `victim` program in the background. The `victim` is one of the ras-tools which allocates a page in userspace and dumps the virtual and physical address of the page, and then holds on to trigger. - -```bash -#victim -d & -[1] 12472 -physical address of (0xffff87fb2000) = 0x89a0f8000 -Hit any key to trigger error: -[1]+ Stopped victim -d -``` - -Then run the bellow script to inject and trigger memory correct error. Note, the CE recovery is usually implemented as a threshold based error reporting mechanism. The default threshold for CE is 5000, in other words, the hardware only signal interrupt per 5000 CE errors. To test the feature, we configure CE threshold as 0. - -```bash -echo 0x89a0f8000 > $APEI_IF/param1 -echo 0xfffffffffffff000 > $APEI_IF/param2 -echo 0x1 > $APEI_IF/flags -echo 0x00000008 > $APEI_IF/error_type -echo 1 > $APEI_IF/error_inject -``` - -The dmesg log: - -```bash -[ 1555.991595] EDAC MC0: 1 CE single-symbol chipkill ECC on unknown memory (node:0 card:0 module:0 rank:0 bank_group:4 bank_address:2 device:0 row:616 column:1024 chip_id:0 page:0x89a0f8 offset:0x0 grain:1 syndrome:0x0 - APEI location: node:0 card:0 module:0 rank:0 bank_group:4 bank_address:2 device:0 row:616 column:1024 chip_id:0 status(0x0000000000000400): Storage error in DRAM memory) -[ 1555.991600] {1}[Hardware Error]: Hardware error from APEI Generic Hardware Error Source: 2 -[ 1555.991602] {1}[Hardware Error]: It has been corrected by h/w and requires no further action -[ 1555.991602] {1}[Hardware Error]: event severity: corrected -[ 1555.991604] {1}[Hardware Error]: precise tstamp: 2023-01-02 17:18:38 -[ 1555.991604] {1}[Hardware Error]: Error 0, type: corrected -[ 1555.991606] {1}[Hardware Error]: section_type: memory error -[ 1555.991606] {1}[Hardware Error]: error_status: Storage error in DRAM memory (0x0000000000000400) -[ 1555.991607] {1}[Hardware Error]: physical_address: 0x000000089a0f8000 -[ 1555.991608] {1}[Hardware Error]: node:0 card:0 module:0 rank:0 bank_group:4 bank_address:2 device:0 row:616 column:1024 chip_id:0 -[ 1555.991609] {1}[Hardware Error]: error_type: 4, single-symbol chipkill ECC -[ 1555.991610] {1}[Hardware Error]: type: DDR (0x50), ras_count:1 -[ 1555.991611] {1}[Hardware Error]: sub_type: 0x0 -[ 1555.991612] {1}[Hardware Error]: fr: 0x1000200000022, ctrl: 0x0, status: 0x0, addr: 0x0 -[ 1555.991612] {1}[Hardware Error]: misc0: 0x0, misc1: 0x0, misc2: 0x200000000000000, misc3: 0x900000000000000 -``` - -##### Memory UnCorrectable Non-fatal - -Firstly, run a `victim` program in the background as the last section described. - -```bash -#victim -d & -physical address of (0xffff962d0000) = 0x9f8acb000 -Hit any key to trigger error: -[1]+ Stopped victim -d -``` - -Then run the bellow script to inject and trigger memory correct error. Here, we specify `notrigger` to 0 to let the firmware kick the DDRC scrubber to trigger the error. - -```bash -APEI_IF=/sys/kernel/debug/apei/einj -echo 0x400a4919000 > $APEI_IF/param1 -echo 0xfffffffffffff000 > $APEI_IF/param2 -echo 0x1 > $APEI_IF/flags -echo 0x00000010 > $APEI_IF/error_type -echo 0x0 > $APEI_IF/notrigger -echo 1 > $APEI_IF/error_inject -``` - -The dmesg log: - -```bash -[ 211.121855] {1}[Hardware Error]: Hardware error from APEI Generic Hardware Error Source: 2 -[ 211.132646] {1}[Hardware Error]: event severity: recoverable -[ 211.138292] {1}[Hardware Error]: precise tstamp: 2022-12-30 15:26:40 -[ 211.144717] {1}[Hardware Error]: Error 0, type: recoverable -[ 211.150362] {1}[Hardware Error]: section_type: memory error -[ 211.156096] {1}[Hardware Error]: error_status: Storage error in DRAM memory (0x0000000000000400) -[ 211.165125] {1}[Hardware Error]: physical_address: 0x00000400a4919000 -[ 211.171725] {1}[Hardware Error]: node:0 card:7 module:0 rank:0 bank_group:7 bank_address:0 device:0 row:146 column:1152 chip_id:0 -[ 211.183619] {1}[Hardware Error]: error_type: 14, scrub uncorrected error -[ 211.190479] {1}[Hardware Error]: type: DDR (0x50), ras_count:1 -[ 211.196383] {1}[Hardware Error]: sub_type: 0x0 -[ 211.200899] {1}[Hardware Error]: fr: 0x1000200000353, ctrl: 0x0, status: 0x0, addr: 0x0 -[ 211.208974] {1}[Hardware Error]: misc0: 0x0, misc1: 0x0, misc2: 0x0, misc3: 0x200000000000500 -[ 211.218375] Memory failure: 0x400a4919: recovery action for dirty LRU page: Recovered -``` - -At this point, the allocated physical page is unmapped and poisoned, any read access will trigger a page fault. -If we move the background process `victim`on current Linux shell to the foreground and hit any key, the victim will trigger a page fault and receive a SIGBUS signal due to the poisoned PTE entry. Because the `victim`process does not register the SIGBUS handler, it will be killed. - -```bash -#fg -victim -d - -Access time at Fri Dec 30 15:38:14 2022 - -Bus error -``` - -We can also specify `notrigger` to 1 to let the firmware skip the trigger phase and allow the `victim` process to access the target of the error injection so that the error will be detected in execution context. - -Firstly, select a page and inject an error to it, while explicitly skipping the firmware trigger phase. - -```bash -#victim -d & -[1] 9522 -physical address of (0xffffaed6d000) = 0x400aa6dd000 -Hit any key to trigger error: -[1]+ Stopped victim -d - -APEI_IF=/sys/kernel/debug/apei/einj - -echo 0x400aa6dd000 > $APEI_IF/param1 -echo 0xfffffffffffff000 > $APEI_IF/param2 -echo 0x1 > $APEI_IF/flags -echo 0x00000010 > $APEI_IF/error_type -echo 0x1 > $APEI_IF/notrigger -echo 1 > $APEI_IF/error_inject -``` - -Then move the background process `victim` on current Linux shell to the foreground and hit any key, so that the error will be triggered in execution context. The kernel will poison the page and unmap it, then send SIGBUS to the process which accesses the page. - -```bash -#fg -victim -d - -Access time at Fri Dec 30 15:39:26 2022 - -Bus error -``` - -The dmesg log: - -```bash -[ 799.958832] {3}[Hardware Error]: Hardware error from APEI Generic Hardware Error Source: 2 -[ 799.969533] {3}[Hardware Error]: event severity: recoverable -[ 799.975179] {3}[Hardware Error]: precise tstamp: 2022-12-30 15:36:29 -[ 799.981603] {3}[Hardware Error]: Error 0, type: recoverable -[ 799.987248] {3}[Hardware Error]: section_type: memory error -[ 799.992978] {3}[Hardware Error]: error_status: Storage error in DRAM memory (0x0000000000000400) -[ 800.002007] {3}[Hardware Error]: physical_address: 0x00000400aa6dd000 -[ 800.008607] {3}[Hardware Error]: node:0 card:5 module:0 rank:1 bank_group:1 bank_address:0 device:0 row:169 column:1664 chip_id:0 -[ 800.020500] {3}[Hardware Error]: error_type: 5, multi-symbol chipkill ECC -[ 800.027446] {3}[Hardware Error]: type: DDR (0x50), ras_count:1 -[ 800.033351] {3}[Hardware Error]: sub_type: 0x0 -[ 800.037866] {3}[Hardware Error]: fr: 0x1001000100000000, ctrl: 0xf000000000920004, status: 0xd800000Cor0040](0xadd040000d0receiveaecntr=526(d1.subch3), cnt=0x1 -[ 800.060436] {3}[Hardware Error]: misc0: 0x3f00000000040307, misc1: 0xd00000000030cd18, misc2: 0x4015, misc3: 0x200000000000100 -[ 800.072366] Memory failure: 0x400aa6dd: recovery action for dirty LRU page: Recovered -``` - -### RAS-tools - -We can also test and validate RAS features of whole system stack across hardware, firmware and OS via ras-tools. Ras-tools are an excellent set of tools to inject and test RAS ability on X86 and Arm64 platforms based on the APEI EINJ interface. - -| tools | fatal | arch | Description | Usage | -| ----------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------ | -| einj_mem_uc | See help | x86、Arm | inject an error and then trigger it in one of a variety of ways. | ./einj_mem_uc # See help for testname | -| cmcistorm | No | x86 | use EINJ to inject a bunch of soft errors, then consume them all as fast as possible. | ./cmcistorm # e.g./cmcistorm 20 1 | -| hornet | No | x86、Arm | Start a process (or point to an existing one) and inject an uncorrectable memory error to a targeted or randomly chosen memory address | ./hornet -p PID | -| lmce | No | x86 | local mce | ./lmce | -| mca-recover | No | x86、Arm | Set up to get zapped by a machine check (injected elsewhere) recovery function reports physical address of new page - so we can inject to that and repeat over and over. | ./mca-recover | -| rep_ce_page | No | x86、Arm | loop using EINJ to inject a soft error, consuming after each until the page is taken offline. | ./rep_ce_page | -| vtop | No | x86、Arm | Given a process if and virtual address, dig around in /proc/id/pagemap to find the physical address (if present) behind the virtual one. | ./vtop | -| memattr | No | Arm | Example of the Linux kernel driver that allows a user-space program to mmap a buffer of contiguous physical memory with specific memory attribute. | cd pgprot-drv
make
insmod pgprot_drv.ko pgprot=4
../memattr| -| ras-tolerance | No | Arm | This driver allows to overwrite error severity to a lower level at runtime, recoverable by default. It is useful for test. | cd ras-tolerance
make
insmod ras_tolerance.ko| - -#### Install - -On servers running Anolis OS, you can install ras-tools through `yum`. On other OSes, you could build it from scratch. - -``` bash -yum install ras-tools -``` - -#### Memory Failure Recovery Validation - -The `einj_mem_uc` tool allocates pages, injects an error and then triggers it in one of a variety of ways. It intends to do a coverage test for testing the Linux RAS related features, including CPU/Memory error containment and recovery. - -##### AR Validation - -###### User Space AR-data Recovery - -In the case of an AR-data abort event e.g. `single`, `doube`,`split`,`hugetlb`,etc, the kernel will attempt to hard-offline the page, by poisoning the page and killing accessing process. For example, `single` case, it injects an uncorrected error and triggers the error by reading a byte. - -```bash -# einj_mem_uc single -0: single vaddr = 0xffff857a3400 paddr = 8e6157400 -injecting ... -triggering ... -signal 7 code 4 addr 0xffff857a3400 -page not present -Test passed -``` - -`einj_mem_uc` will print the received signal and its code, in the above case, - -- signal 7: SIGBUS -- code 4: BUS_MCEERR_AR 4 - -The dmesg log: - -```bash -[ 1785.908893] EDAC MC0: 1 UE multi-symbol chipkill ECC on unknown memory (node:0 card:0 module:0 rank:0 bank_group:1 bank_address:2 device:0 row:920 column:896 chip_id:0 page:0x8e6157 offset:0x400 grain:1 - APEI location: node:0 card:0 module:0 rank:0 bank_group:1 bank_address:2 device:0 row:920 column:896 chip_id:0 status(0x0000000000000400): Storage error in DRAM memory) -[ 1785.908900] {1}[Hardware Error]: Hardware error from APEI Generic Hardware Error Source: 2 -[ 1785.919531] {1}[Hardware Error]: event severity: recoverable -[ 1785.925176] {1}[Hardware Error]: precise tstamp: 2023-01-17 18:05:09 -[ 1785.931600] {1}[Hardware Error]: Error 0, type: recoverable -[ 1785.937244] {1}[Hardware Error]: section_type: memory error -[ 1785.942975] {1}[Hardware Error]: error_status: Storage error in DRAM memory (0x0000000000000400) -[ 1785.952004] {1}[Hardware Error]: physical_address: 0x00000008e6157400 -[ 1785.958603] {1}[Hardware Error]: node:0 card:0 module:0 rank:0 bank_group:1 bank_address:2 device:0 row:920 column:896 chip_id:0 -[ 1785.970409] {1}[Hardware Error]: error_type: 5, multi-symbol chipkill ECC -[ 1785.977355] {1}[Hardware Error]: type: DDR (0x50), common_reg_nr:1 -[ 1785.983606] {1}[Hardware Error]: Synchronous Exception taken in EL0 -[ 1785.989944] {1}[Hardware Error]: ESR: 0x92000410, ELR: 0x403abc, FAR: 0xfa00a88, SCR: 0x403073d, SCTLR: 0x30cd183f, LR: 0x403abc -[ 1786.001578] {1}[Hardware Error]: ECCERRCNT: 0x10000, ECCSTAT: 0x0, ADVECCSTAT: 0x8000002, ECCSYMBOL: 0x170000, ECCERRCNTSTAT: 0x0, ECCERRCNT0: 0x0, ECCERRCNT1: 0x0, ECCCADDR0: 0x0, ECCCADDR1: 0x0, ECCCDATA0: 0x0, ECCCDATA1: 0x0, ECCUADDR0: 0x398, ECCUADDR1: 0x1020380, ECCUDATA0: 0x1ff, ECCUDATA1: 0x0 -[ 1786.036640] Memory failure: 0x8e6157: recovery action for dirty LRU page: Recovered - -``` - -###### User Space AR-instruction Recovery - -In the case of an AR-instruction abort event, e.g. `instr`, it injects an uncorrected error and triggers the error by reading a byte. The kernel will attempt to hard-offline the page. It unmaps the corrupted page, reloads the 4KB page containing the instruction to a new physical page and resumes normal operation. - -```bash -# einj_mem_uc instr -0: instr vaddr = 0x403000 paddr = 8bba93000 -injecting ... -triggering ... -Test passed -``` - -The dmesg log: - -```bash -[ 1945.804589] EDAC MC0: 1 UE multi-symbol chipkill ECC on unknown memory (node:0 card:7 module:0 rank:1 bank_group:1 bank_address:3 device:0 row:527 column:640 chip_id:0 page:0x40883e65 offset:0x0 grain:1 - APEI location: node:0 card:7 module:0 rank:1 bank_group:1 bank_address:3 device:0 row:527 column:640 chip_id:0 status(0x0000000000000400): Storage error in DRAM memory) -[ 1945.804596] {3}[Hardware Error]: Hardware error from APEI Generic Hardware Error Source: 2 -[ 1945.815209] {3}[Hardware Error]: event severity: recoverable -[ 1945.820854] {3}[Hardware Error]: precise tstamp: 2023-01-17 18:07:49 -[ 1945.827280] {3}[Hardware Error]: Error 0, type: recoverable -[ 1945.832924] {3}[Hardware Error]: section_type: memory error -[ 1945.838654] {3}[Hardware Error]: error_status: Storage error in DRAM memory (0x0000000000000400) -[ 1945.847683] {3}[Hardware Error]: physical_address: 0x0000040883e65000 -[ 1945.854283] {3}[Hardware Error]: node:0 card:7 module:0 rank:1 bank_group:1 bank_address:3 device:0 row:527 column:640 chip_id:0 -[ 1945.866089] {3}[Hardware Error]: error_type: 5, multi-symbol chipkill ECC -[ 1945.873035] {3}[Hardware Error]: type: DDR (0x50), common_reg_nr:1 -[ 1945.879286] {3}[Hardware Error]: Synchronous Exception taken in EL0 -[ 1945.885625] {3}[Hardware Error]: ESR: 0x82000010, ELR: 0x403000, FAR: 0x403000, SCR: 0x403073d, SCTLR: 0x30cd183f, LR: 0x403f94 -[ 1945.906459] {3}[Hardware Error]: ECCERRCNT: 0x10000, ECCSTAT: 0x0, ADVECCSTAT: 0x8000002, ECCSYMBOL: 0x140000, ECCERRCNTSTAT: 0x0, ECCERRCNT0: 0x0, ECCERRCNT1: 0x0, ECCCADDR0: 0x0, ECCCADDR1: 0x0, ECCCDATA0: 0x0, ECCCDATA1: 0x0, ECCUADDR0: 0x100020f, ECCUADDR1: 0x1030280, ECCUDATA0: 0x1ff, ECCUDATA1: 0x0 -[ 1945.934071] Memory failure: 0x40883e65: corrupted page was clean: dropped without side effects -[ 1945.934084] Memory failure: 0x40883e65: recovery action for clean LRU page: Recovered -``` - -###### Kernel Space AR Recovery - -Kernel Space AR Recovery is only supported on X86 platform and we are still working on it on Arm64 platform. The recovery is evaluated on X86 icelake processor. - -First, inject an uncorrected error and trigger it by writing a buffer to a file. Kernel will copy data from user space and then write to disk. - -```bash -# einj_mem_uc copyin -f -0: copyin vaddr = 0x7f8f873e2400 paddr = 2869c1400 -injecting ... -triggering ... -einj_mem_uc: couldn't write temp file (errno=14) -Big surprise ... still running. Thought that would be fatal -Saw local machine check -Test passed -``` - -As we can see, the process is still running and the return errno for the write(2) is EFAULT(14). - -The dmesg log: - -```bash -SetMemoryDeviceStatus UCE error. Data = 00 4C A5 01 02 00 06 01 05 00 00 00 00 00 Status = Success -[15322.535921] mce: Kernel accessed poison in user space at 2869c1400 -[15322.536023] {2}[Hardware Error]: Hardware error from APEI Generic Hardware Error Source: 0 -[15322.542117] Memory failure: 0x2869c1: recovery action for dirty LRU page: Recovered -[15322.550382] {2}[Hardware Error]: event severity: recoverable -[15322.550385] {2}[Hardware Error]: Error 0, type: recoverable -[15322.558042] Memory failure: 0x2869c1: already hardware poisoned -[15322.563710] {2}[Hardware Error]: fru_text: Card02, ChnF, DIMM0 -[15322.563712] {2}[Hardware Error]: section_type: memory error -[15322.586981] {2}[Hardware Error]: error_status: Storage error in DRAM memory (0x0000000000000400) -[15322.596027] {2}[Hardware Error]: physical_address: 0x00000002869c1400 -[15322.602650] {2}[Hardware Error]: node:1 card:5 module:0 rank:0 bank:13 device:0 row:2075 column:8 -[15322.611783] {2}[Hardware Error]: error_type: 3, multi-bit ECC -[15322.617710] {2}[Hardware Error]: DIMM location: not present. DMI handle: 0x0000 -[15322.625304] Memory failure: 0x2869c1: already hardware poisoned -[15322.631827] EDAC MC6: 1 UE memory read error on CPU_SrcID#1_MC#2_Chan#1_DIMM#0 (channel:1 slot:0 page:0x2869c1 offset:0x400 grain:32 - err_code:0x00a0:0x0091 SystemAddress:0x2869c1400 ProcessorSocketId:0x1 MemoryControllerId:0x2 ChannelAddress:0x2069c000 ChannelId:0x1 RankAddress:0x1034e000 PhysicalRankId:0x0 DimmSlotId:0x0 Row:0x81b Column:0x8 Bank:0x1 BankGroup:0x3 ChipSelect:0x0 ChipId:0x0) -[15322.667403] EDAC MC6: 1 UE memory read error on CPU_SrcID#1_MC#2_Chan#1_DIMM#0 (channel:1 slot:0 page:0x2869c1 offset:0x400 grain:32 - err_code:0x0000:0x009f SystemAddress:0x2869c1400 ProcessorSocketId:0x1 MemoryControllerId:0x2 ChannelAddress:0x2069c000 ChannelId:0x1 RankAddress:0x1034e000 PhysicalRankId:0x0 DimmSlotId:0x0 Row:0x81b Column:0x8 Bank:0x1 BankGroup:0x3 ChipSelect:0x0 ChipId:0x0) -``` - -futex(2) is another system call in which kernel copies data from user space. Inject an uncorrected error and trigger it by issuing `FUTEX_WAIT` operation. - -```bash -# einj_mem_uc futex -f -0: futex vaddr = 0x7f8a1da83400 paddr = 25751d400 -injecting ... -triggering ... -futex returned with errno=14 -Big surprise ... still running. Thought that would be fatal -Unusual number of MCEs seen: 2 -Test passed -``` - -There are many retries in futex(2) mechanism, so it is possible to see many MCEs. - -The dmesg log: - -```bash -SetMemoryDeviceStatus UCE error. Data = 00 4C A5 01 02 00 06 01 05 00 00 00 00 00 Status = Success -[15521.242381] mce: Kernel accessed poison in user space at 25751d400 -[15521.242437] {4}[Hardware Error]: Hardware error from APEI Generic Hardware Error Source: 0 -[15521.248581] Memory failure: 0x25751d: recovery action for dirty LRU page: Recovered -[15521.256842] {4}[Hardware Error]: event severity: recoverable -[15521.256845] {4}[Hardware Error]: Error 0, type: recoverable -[15521.256847] {4}[Hardware Error]: fru_text: Card02, ChnF, DIMM0 -[15521.264506] Memory failure: 0x25751d: already hardware poisoned -[15521.270172] {4}[Hardware Error]: section_type: memory error -[15521.270173] {4}[Hardware Error]: error_status: Storage error in DRAM memory (0x0000000000000400) -[15521.270174] {4}[Hardware Error]: physical_address: 0x000000025751d400 -[15521.309103] {4}[Hardware Error]: node:1 card:5 module:0 rank:0 bank:4 device:0 row:1882 column:896 -[15521.318322] {4}[Hardware Error]: error_type: 3, multi-bit ECC -[15521.324252] {4}[Hardware Error]: DIMM location: not present. DMI handle: 0x0000 -[15521.331824] {4}[Hardware Error]: Error 1, type: recoverable -[15521.337484] {4}[Hardware Error]: section_type: memory error -[15521.343240] {4}[Hardware Error]: error_status: Storage error in DRAM memory (0x0000000000000400) -[15521.352286] {4}[Hardware Error]: physical_address: 0x000000025751d400 -[15521.358910] {4}[Hardware Error]: node:1 -[15521.363017] {4}[Hardware Error]: error_type: 3, multi-bit ECC -[15521.369040] Memory failure: 0x25751d: already hardware poisoned -[15521.374974] Memory failure: 0x25751d: already hardware poisoned -[15521.381515] EDAC MC6: 1 UE memory read error on CPU_SrcID#1_MC#2_Chan#1_DIMM#0 (channel:1 slot:0 page:0x25751d offset:0x400 grain:32 - err_code:0x00a0:0x0091 SystemAddress:0x25751d400 ProcessorSocketId:0x1 MemoryControllerId:0x2 ChannelAddress:0x1d751c00 ChannelId:0x1 RankAddress:0xeba9c00 PhysicalRankId:0x0 DimmSlotId:0x0 Row:0x75a Column:0x380 Bank:0x0 BankGroup:0x1 ChipSelect:0x0 ChipId:0x0) -[15521.417060] EDAC MC6: 1 UE memory read error on CPU_SrcID#1_MC#2_Chan#1_DIMM#0 (channel:1 slot:0 page:0x25751d offset:0x400 grain:32 - err_code:0x0000:0x009f SystemAddress:0x25751d400 ProcessorSocketId:0x1 MemoryControllerId:0x2 ChannelAddress:0x1d751c00 ChannelId:0x1 RankAddress:0xeba9c00 PhysicalRankId:0x0 DimmSlotId:0x0 Row:0x75a Column:0x380 Bank:0x0 BankGroup:0x1 ChipSelect:0x0 ChipId:0x0) -[15521.452740] EDAC MC6: 1 UE memory read error on CPU_SrcID#1_MC#2_Chan#1_DIMM#0 (channel:1 slot:0 page:0x25751d offset:0x400 grain:32 - err_code:0x0000:0x009f SystemAddress:0x25751d400 ProcessorSocketId:0x1 MemoryControllerId:0x2 ChannelAddress:0x1d751c00 ChannelId:0x1 RankAddress:0xeba9c00 PhysicalRankId:0x0 DimmSlotId:0x0 Row:0x75a Column:0x380 Bank:0x0 BankGroup:0x1 ChipSelect:0x0 ChipId:0x0) -``` - -##### AO Validation - -###### AO Patrol Recovery - -In the case of an AO event e.g. `patrol`, the kernel will attempt to hard-offline the page, by just poisoning and unmapping the page. Inject and trigger patrol error. Note, in this section, the HWPoison-aware strategy is default late kill. - -```bash -# einj_mem_uc patrol -0: patrol vaddr = 0xffff9d523400 paddr = 400a2575400 -injecting ... -triggering ... -page not present -Test passed -``` - -The dmesg log: - -```bash -[ 2026.290450] EDAC MC0: 1 UE scrub uncorrected error on unknown memory (node:0 card:6 module:0 rank:0 bank_group:2 bank_address:3 device:0 row:137 column:640 chip_id:0 page:0x400a2575 offset:0x400 grain:1 - APEI location: node:0 card:6 module:0 rank:0 bank_group:2 bank_address:3 device:0 row:137 column:640 chip_id:0 status(0x0000000000000400): Storage error in DRAM memory) -[ 2026.290460] {4}[Hardware Error]: Hardware error from APEI Generic Hardware Error Source: 2 -[ 2026.301258] {4}[Hardware Error]: event severity: recoverable -[ 2026.306903] {4}[Hardware Error]: precise tstamp: 2023-01-17 18:09:10 -[ 2026.313328] {4}[Hardware Error]: Error 0, type: recoverable -[ 2026.318972] {4}[Hardware Error]: section_type: memory error -[ 2026.324703] {4}[Hardware Error]: error_status: Storage error in DRAM memory (0x0000000000000400) -[ 2026.333732] {4}[Hardware Error]: physical_address: 0x00000400a2575400 -[ 2026.340331] {4}[Hardware Error]: node:0 card:6 module:0 rank:0 bank_group:2 bank_address:3 device:0 row:137 column:640 chip_id:0 -[ 2026.352138] {4}[Hardware Error]: error_type: 14, scrub uncorrected error -[ 2026.358998] {4}[Hardware Error]: type: DDR (0x50), common_reg_nr:1 -[ 2026.365249] {4}[Hardware Error]: Interrupt: 843 -[ 2026.369852] {4}[Hardware Error]: ECCERRCNT: 0x40000, ECCSTAT: 0x0, ADVECCSTAT: 0x88000002, ECCSYMBOL: 0xec0000, ECCERRCNTSTAT: 0x0, ECCERRCNT0: 0x0, ECCERRCNT1: 0x0, ECCCADDR0: 0x0, ECCCADDR1: 0x0, ECCCDATA0: 0x0, ECCCDATA1: 0x0, ECCUADDR0: 0x89, ECCUADDR1: 0x2030280, ECCUDATA0: 0x1ff, ECCUDATA1: 0x0 -[ 2026.397264] Memory failure: 0x400a2575: recovery action for dirty LRU page: Recovered -``` - -###### AO Prefetch Recovery - -First, inject an uncorrected error and trigger it by explicitly performing a `prfm`. The platform will signal an interrupt. - -```bash -#einj_mem_uc prefetch -0: prefetch vaddr = 0xffffbe03f400 paddr = 8c17eb400 -injecting ... -triggering ... -page not present -Test passed -``` - -The dmesg log: - -```bash -[ 7616.802823] {1}[Hardware Error]: Hardware error from APEI Generic Hardware Error Source: 2 -[ 7616.813922] {1}[Hardware Error]: event severity: recoverable -[ 7616.819566] {1}[Hardware Error]: Error 0, type: recoverable -[ 7616.825210] {1}[Hardware Error]: section_type: memory error -[ 7616.830940] {1}[Hardware Error]: error_status: 0x0000000000000400 -[ 7616.837191] {1}[Hardware Error]: physical_address: 0x00000008c17eb400 -[ 7616.843791] {1}[Hardware Error]: node: 0 card: 0 module: 0 rank: 1 bank_group: 3 bank_address: 0 device: 0 row: 773 column: 1408 -[ 7616.855597] {1}[Hardware Error]: error_type: 5, multi-symbol chipkill ECC -[ 7616.862543] {1}[Hardware Error]: type: DDR (0x50), ras_count:1 -[ 7616.868447] {1}[Hardware Error]: sub_type: 0x0 -[ 7616.872962] {1}[Hardware Error]: fr: 0x1000200000026, ctrl: 0x0, status: 0x0, addr: 0x0 -[ 7616.881036] {1}[Hardware Error]: misc0: 0x0, misc1: 0x0, misc2: 0x0, misc3: 0x200000000000100 -[ 7616.889888] Memory failure: 0x8c17eb: recovery action for dirty LRU page: Recovered -``` - -###### AO Store Recovery - -First, inject an uncorrected error and trigger it by writing a byte. The write size is less than 64 bits and the platform will signal a SError. - -```bash -# einj_mem_uc strbyte -0: strbyte vaddr = 0xffffa3651400 paddr = 400afd01400 -injecting ... -triggering ... -page not present -Test passed -``` - -The dmesg log: - -```bash -[ 2378.241939] EDAC MC0: 1 UE multi-symbol chipkill ECC on unknown memory (node:0 card:5 module:0 rank:0 bank_group:2 bank_address:1 device:0 row:191 column:128 chip_id:0 page:0x400afd01 offset:0x400 grain:1 - APEI location: node:0 card:5 module:0 rank:0 bank_group:2 bank_address:1 device:0 row:191 column:128 chip_id:0 status(0x0000000000000400): Storage error in DRAM memory) -[ 2378.241945] {5}[Hardware Error]: Hardware error from APEI Generic Hardware Error Source: 2 -[ 2378.252573] {5}[Hardware Error]: event severity: recoverable -[ 2378.258217] {5}[Hardware Error]: precise tstamp: 2023-01-17 18:15:02 -[ 2378.264642] {5}[Hardware Error]: Error 0, type: recoverable -[ 2378.270286] {5}[Hardware Error]: section_type: memory error -[ 2378.276017] {5}[Hardware Error]: error_status: Storage error in DRAM memory (0x0000000000000400) -[ 2378.285045] {5}[Hardware Error]: physical_address: 0x00000400afd01400 -[ 2378.291644] {5}[Hardware Error]: node:0 card:5 module:0 rank:0 bank_group:2 bank_address:1 device:0 row:191 column:128 chip_id:0 -[ 2378.303451] {5}[Hardware Error]: error_type: 5, multi-symbol chipkill ECC -[ 2378.310398] {5}[Hardware Error]: type: DDR (0x50), common_reg_nr:1 -[ 2378.316649] {5}[Hardware Error]: SError -[ 2378.320558] {5}[Hardware Error]: ECCERRCNT: 0x10000, ECCSTAT: 0x0, ADVECCSTAT: 0x8000002, ECCSYMBOL: 0x6f0000, ECCERRCNTSTAT: 0x0, ECCERRCNT0: 0x0, ECCERRCNT1: 0x0, ECCCADDR0: 0x0, ECCCADDR1: 0x0, ECCCDATA0: 0x0, ECCCDATA1: 0x0, ECCUADDR0: 0xbf, ECCUADDR1: 0x2010080, ECCUDATA0: 0x1ff, ECCUDATA1: 0x0 -[ 2378.360399] Memory failure: 0x400afd01: recovery action for dirty LRU page: Recovered -``` - -In contrast, inject an uncorrected error and trigger it by writing a quad word. The write size is 64 bits and the platform will not signal SErrors. - -```bash -# einj_mem_uc strqword -0: strqword vaddr = 0xffff991b5400 paddr = 92b73c400 -injecting ... -triggering ... -Manually take page offline -Test passed -``` - -The dmesg log: - -```bash -[270286.564242] Memory failure: 0x92b73c: recovery action for dirty LRU page: Recovered -``` - -##### QEMU Validation - -First, start a VM with a stdio monitor which allows giving complex commands to the QEMU emulator. - -```bash -qemu-system-aarch64 -enable-kvm \ - -cpu host \ - -M virt,gic-version=3 \ - -m 8G \ - -d guest_errors \ - -rtc base=localtime,clock=host \ - -smp cores=2,threads=2,sockets=2 \ - -object memory-backend-ram,id=mem0,size=4G \ - -object memory-backend-ram,id=mem1,size=4G \ - -numa node,memdev=mem0,cpus=0-3,nodeid=0 \ - -numa node,memdev=mem1,cpus=4-7,nodeid=1 \ - -bios /usr/share/AAVMF/AAVMF_CODE.fd \ - -drive driver=qcow2,media=disk,cache=writeback,if=virtio,id=alinu1_rootfs,file=/media/nvme/shawn.xs/qemu/aliyun_3_arm64_20G_alpha_alibase_20210425.qcow2 \ - -netdev user,id=n1,hostfwd=tcp::5555-:22 \ - -serial telnet:localhost:4321,server,nowait \ - -device virtio-net-pci,netdev=n1 \ - -monitor stdio -QEMU 7.2.0 monitor - type 'help' for more information -(qemu) VNC server running on 127.0.0.1:5900 -``` - -Login guest and install ras-tools, then run `einj_mem_uc` to allocate a page in userspace, dumps the virtual and physical address of the page. The `-j` is to skip error injection and `-k` is to wait for a kick. - -``` bash -$ einj_mem_uc single -j -k -0: single vaddr = 0xffffb2f27000 paddr = 154aba000 -``` - -Run command `gpa2hpa` in QEMU monitor and it will print the host physical address at which the guest’s physical address addr is mapped. - -``` bash -(qemu) gpa2hpa 0x151f21400 -Host physical address for 0x154aba000 (mem1) is 0x92b3c5000 -``` - -Inject an uncorrected error via the APEI interface to the finally translated host physical address on host. - -``` bash -echo 0x92b3c5000 > /sys/kernel/debug/apei/einj/param1 -echo 0xfffffffffffff000 > /sys/kernel/debug/apei/einj/param2 -echo 0x0 > /sys/kernel/debug/apei/einj/flags -echo 0x10 > /sys/kernel/debug/apei/einj/error_type -echo 1 > /sys/kernel/debug/apei/einj/notrigger -echo 1 > /sys/kernel/debug/apei/einj/error_inject -``` - -Then kick `einj_mem_uc` to trigger the error by writing "trigger_start". In this example, the kick is done on host. - -``` bash -#ssh -p 5555 root@localhost "echo trigger > ~/trigger_start" -``` - -We will observe that the QEMU process exit. - -``` bash -(qemu) qemu-system-aarch64: Hardware memory error! -``` - -The dmesg log: - -``` bash -[ 2705.654424] EDAC MC0: 1 UE multi-symbol chipkill ECC on unknown memory (node:0 card:0 module:0 rank:1 bank_group:4 bank_address:2 device:0 row:1196 column:640 chip_id:0 page:0x92b3c5 offset:0x0 grain:1 - APEI location: node:0 card:0 module:0 rank:1 bank_group:4 bank_address:2 device:0 row:1196 column:640 chip_id:0 status(0x0000000000000400): Storage error in DRAM memory) -[ 2705.654432] {6}[Hardware Error]: Hardware error from APEI Generic Hardware Error Source: 2 -[ 2705.665047] {6}[Hardware Error]: event severity: recoverable -[ 2705.670692] {6}[Hardware Error]: precise tstamp: 2023-01-17 18:20:29 -[ 2705.677118] {6}[Hardware Error]: Error 0, type: recoverable -[ 2705.682762] {6}[Hardware Error]: section_type: memory error -[ 2705.688492] {6}[Hardware Error]: error_status: Storage error in DRAM memory (0x0000000000000400) -[ 2705.697521] {6}[Hardware Error]: physical_address: 0x000000092b3c5000 -[ 2705.704121] {6}[Hardware Error]: node:0 card:0 module:0 rank:1 bank_group:4 bank_address:2 device:0 row:1196 column:640 chip_id:0 -[ 2705.716014] {6}[Hardware Error]: error_type: 5, multi-symbol chipkill ECC -[ 2705.722960] {6}[Hardware Error]: type: DDR (0x50), common_reg_nr:1 -[ 2705.729212] {6}[Hardware Error]: Synchronous Exception taken in EL0 -[ 2705.735551] {6}[Hardware Error]: ESR: 0x92000410, ELR: 0x401880, FAR: 0xffffb2e8c1d8, SCR: 0x403073d, SCTLR: 0x30cd183f, LR: 0x401840 -[ 2705.747619] {6}[Hardware Error]: ECCERRCNT: 0x10000, ECCSTAT: 0x0, ADVECCSTAT: 0x8000002, ECCSYMBOL: 0x60000, ECCERRCNTSTAT: 0x0, ECCERRCNT0: 0x0, ECCERRCNT1: 0x0, ECCCADDR0: 0x0, ECCCADDR1: 0x0, ECCCDATA0: 0x0, ECCCDATA1: 0x0, ECCUADDR0: 0x10004ac, ECCUADDR1: 0x4020280, ECCUDATA0: 0x1ff, ECCUDATA1: 0x0 -[ 2705.887179] EDAC MC0: 1 UE multi-symbol chipkill ECC on unknown memory (node:0 card:0 module:0 rank:1 bank_group:4 bank_address:2 device:0 row:1196 column:640 chip_id:0 page:0x92b3c5 offset:0x0 grain:1 - APEI location: node:0 card:0 module:0 rank:1 bank_group:4 bank_address:2 device:0 row:1196 column:640 chip_id:0 status(0x0000000000000400): Storage error in DRAM memory) -[ 2705.887181] {7}[Hardware Error]: Hardware error from APEI Generic Hardware Error Source: 2 -[ 2705.897824] {7}[Hardware Error]: event severity: recoverable -[ 2705.903468] {7}[Hardware Error]: precise tstamp: 2023-01-17 18:20:29 -[ 2705.909893] {7}[Hardware Error]: Error 0, type: recoverable -[ 2705.915537] {7}[Hardware Error]: section_type: memory error -[ 2705.921267] {7}[Hardware Error]: error_status: Storage error in DRAM memory (0x0000000000000400) -[ 2705.930296] {7}[Hardware Error]: physical_address: 0x000000092b3c5000 -[ 2705.936895] {7}[Hardware Error]: node:0 card:0 module:0 rank:1 bank_group:4 bank_address:2 device:0 row:1196 column:640 chip_id:0 -[ 2705.948790] {7}[Hardware Error]: error_type: 5, multi-symbol chipkill ECC -[ 2705.955736] {7}[Hardware Error]: type: DDR (0x50), common_reg_nr:1 -[ 2705.961988] {7}[Hardware Error]: Synchronous Exception taken in EL0 -[ 2705.968326] {7}[Hardware Error]: ESR: 0x92000410, ELR: 0x401880, FAR: 0xffffb2e8c1d8, SCR: 0x403073d, SCTLR: 0x30cd183f, LR: 0x401840 -[ 2705.980394] {7}[Hardware Error]: ECCERRCNT: 0x0, ECCSTAT: 0x0, ADVECCSTAT: 0x0, ECCSYMBOL: 0x0, ECCERRCNTSTAT: 0x0, ECCERRCNT0: 0x0, ECCERRCNT1: 0x0, ECCCADDR0: 0x0, ECCCADDR1: 0x0, ECCCDATA0: 0x0, ECCCDATA1: 0x0, ECCUADDR0: 0x10004ac, ECCUADDR1: 0x4020280, ECCUDATA0: 0x0, ECCUDATA1: 0x0 -[ 2706.006235] Memory failure: 0x92b3c5: Sending SIGBUS to qemu-system-aar:32293 due to hardware memory corruption -[ 2706.078549] Memory failure: 0x92b3c5: recovery action for dirty LRU page: Recovered -[ 2706.092539] Memory failure: 0x92b3c5: already hardware poisoned -[ 2706.118501] EDAC MC0: 1 UE multi-symbol chipkill ECC on unknown memory (node:0 card:0 module:0 rank:0 bank_group:1 bank_address:2 device:0 row:920 column:896 chip_id:0 page:0x0 offset:0x0 grain:1 - APEI location: node:0 card:0 module:0 rank:0 bank_group:1 bank_address:2 device:0 row:920 column:896 chip_id:0 status(0x0000000000000400): Storage error in DRAM memory) -``` - -Note, QEMU registers SIGBUS handler and sets `PR_MCE_KILL_EARLY` by `prctl`. When an AO error occurs, e.g. detected by scrubber, kernel will also send SIGBUS but with sicode `BUS_MCEERR_AO 5`. - -##### HWPoison-aware Strategy - -First, check the strategy on your system. - -```bash -#sysctl vm.memory_failure_early_kill -vm.memory_failure_early_kill = 0 -``` - -Change to early kill mode: - -```bash -#sysctl -w vm.memory_failure_early_kill=1 -vm.memory_failure_early_kill = 1 -``` - -Then inject a `patrol` error to see the kernel behavior. - -```bash -#./einj_mem_uc patrol -0: patrol vaddr = 0xffffbe4b8400 paddr = 901656400 -injecting ... -triggering ... -signal 7 code 5 addr 0xffffbe4b8000 -Unexpected SIGBUS -page not present -Test passed -``` - -As we expected, the kernel sends SIGBUS to kill the process even though it does not access the poison data. The `code 5` here means `BUS_MCEERR_AO 5`. - -#### Memory Predictive Failure Analysis Validation - -First of all, you'll need to install **rasdeamon**, it's packaged for most Linux distributions: - -```bash -yum install rasdaemon -``` - -Then we'll setup **rasdaemon** to launch at startup and to record events to an on-disk sqlite database. - -```bash -# systemctl enable rasdaemon -# systemctl start rasdaemon -``` - -Here, we manually change the `PAGE_CE_THRESHOLD="5"` in config file `/etc/sysconfig/rasdaemon` so that we can inject and exceed a page error threshold more easily. Note, run-time configuration is unsupported, service restart is needed. - -```bash -# systemctl restart rasdaemon -``` - -Run `victim` with `-p` option to help test PFA function. The `victim` allocates a page in userspace, dumps the virtual and physical address of the page, and checks the physical address in a loop while. Then inject to the physical address 5 times and it will trigger soft action in which kernel soft-offline the old page, by moving the contents to a new page. - -```bash -#victim -d -p -physical address of (0xffffa5a66000) = 0x967cf1000 -Page was replaced. New physical address = 0x8bce3e000 -``` - -## Acknowledgment - -Thanks to the developers who contributed to the Linux and Anolis communities. - -## Reference - -1. [https://www.intel.com/content/www/us/en/developer/articles/technical/new-reliability-availability-and-serviceability-ras-features-in-the-intel-xeon-processor.html](https://www.intel.com/content/www/us/en/developer/articles/technical/new-reliability-availability-and-serviceability-ras-features-in-the-intel-xeon-processor.html) -2. Reliability, Availability and Serviceability (RAS) Integration and Validation Guide for the Intel® Xeon® Processor E7- v3 Family: [https://www.intel.com/content/dam/develop/external/us/en/documents/emca2-integration-validation-guide-556978.pdf](https://www.intel.com/content/dam/develop/external/us/en/documents/emca2-integration-validation-guide-556978.pdf) -3. [https://docs.kernel.org/admin-guide/ras.html](https://docs.kernel.org/admin-guide/ras.html) -4. [https://static.linaro.org/connect/sfo17/Presentations/SFO17-203%20-%20Reliability%2C%20Availability%2C%20and%20Serviceability%20%28RAS%29%20on%20ARM64%20status.pdf](https://static.linaro.org/connect/sfo17/Presentations/SFO17-203%20-%20Reliability%2C%20Availability%2C%20and%20Serviceability%20%28RAS%29%20on%20ARM64%20status.pdf) -5. Intel® 64 and IA-32 Architectures Software Developer’s Manual -6. [https://developer.ibm.com/articles/l-kernel-memory-access/](https://developer.ibm.com/articles/l-kernel-memory-access/) -7. [https://docs.kernel.org/admin-guide/sysctl/vm.html#memory-failure-early-kill](https://docs.kernel.org/admin-guide/sysctl/vm.html#memory-failure-early-kill) -8. Programming persistent memory: A comprehensive guide for developers -9. [https://trustedfirmware-a.readthedocs.io/en/latest/components/sdei.html](https://trustedfirmware-a.readthedocs.io/en/latest/components/sdei.html#id2) - -TEST 2024年7月2日14:09:20 \ No newline at end of file diff --git a/PRODUCT_DOCS/test/test2.md b/PRODUCT_DOCS/test/test2.md deleted file mode 100644 index 2cc3621b3c2d05f0ed3dca275171fbb5e2c1e656..0000000000000000000000000000000000000000 --- a/PRODUCT_DOCS/test/test2.md +++ /dev/null @@ -1,40 +0,0 @@ -## 与会人 -看下修改时间 - -王云志，何佳，黄睿，王宝林，云孟，荆石，刘长生(搏元）， -疏明，何求，章新豪
-费斐，帅家坤，Joyce(Linaro)，Chase Qi(Linaro) -- 本次轮值主持：贺军 -- 下次轮值主持：王宝林 - -## 主题 -### 1. Arm architectural features support in kernel and toolchain -[Arm A-profile 架构手册](https://developer.arm.com/documentation/ddi0487/latest/) - -Arm架构的各个版本特性的软件支持情况链接： -- Linux Kernel: https://developer.arm.com/Tools%20and%20Software/Linux%20Kernel#Components -- GCC: https://developer.arm.com/Tools%20and%20Software/GNU%20Toolchain#Supported-Devices -- LLVM: https://developer.arm.com/Tools%20and%20Software/LLVM%20Toolchain#Supported-Devices - -### 2. Kernel test - LKFT introduction -- 来自Linaro的Chase介绍了[Linaro LKFT平台](https://lkft.linaro.org/tests/)的测试流程、用例和支持的硬件 -- 来自阿里的疏明介绍了目前龙蜥社区的测试情况 - - 社区使用T-One(https://tone.openanolis.cn/)做为测试平台，默认覆盖x86和Arm。 测试硬件是Ali ECS的实例。 - - 对CloudKernel的测试构建以build和boot为主；也有通用的regression测试。常用测试方式包括ltp，kselftest和xfstest等 - - 社区需要针对Arm处理器features的专门测试集（类似于lkvs） - - Arm方面会对此调研，并作后续沟通讨论 -### 3. Live patch on Arm -- 来自Arm的何佳介绍了Arm平台上live patch功能在Linux kernel上游和国内distro社区的支持情况，探讨了不同实现方式的局限性和未来的主流做法。 -- 龙蜥社区对目前5.10中的对Live patch的支持方式没有计划进行改动以保持对上游kernel的一致。 - - Arm建议给出相应文档以方便下游OSV和开发者制作正确的patch -- 对LTS选定的6.6内核，Arm SIG同意以kernel上游社区的实现（patch原型）为基础，进行backport。测试覆盖以kselftest和hotfix为标准。 -### 4. Arm SIG例会形式 -参会者同意以双周会的方式举办例会，具体形式为每两周的周二上午10点。此前议题的收集以邮件列表和钉钉群为主，到达率不高，需要考虑其他更公开方便的途径。 - - -## 遗留问题/跟进任务 -1. 王宝林：调研收集议题的途径 -2. ASDFASDFASDF -3. ASDF -4. ASDFASD -5. FASF \ No newline at end of file diff --git a/PRODUCT_DOCS/test/test3.md b/PRODUCT_DOCS/test/test3.md deleted file mode 100644 index 6b0b76a894c3c26b576c5535654b5d7dfc5961f0..0000000000000000000000000000000000000000 --- a/PRODUCT_DOCS/test/test3.md +++ /dev/null @@ -1,120 +0,0 @@ -# Anolis OS Cloud Kernel: datop技术设计细则 -## 概述 -在本文中，我们基于社区DAMON设计用于跟踪实时内存热点数据的工具DATOP， 采用划分内存区域采样的方式，并自适应区域构建技术来获取极低的开销损耗，在此基础上，还增加了numa 仿真功能，用于收集任务跨numa访存情况，为了评估其准确性和低开销能力，我们选取和测试了多个benchmark，并与基线进行比较, 结果表明：DATOP工具运行时开销非常小(保持在不到4%左右)，此外开销不受负载大小的影响，仍然保持出色的监控质量，通过多方面测试，我们得出结论：DATOP工具在识别冷热内存以及跨numa访存方面具备优秀的表现能力。 - -## 背景：云计算大规模复杂场景下内存面临的挑战 -云计算领域场景下，海量用户数据的增长，对计算机软件和硬件设计都带来了巨大的挑战，尤其是内存设备如DRAM的速率提升并没有跟上这种高速增长趋势，在数据中心中，海量数据的处理，常常让服务器饱受内存不足之苦。 - -为克服低内存容量，混合内存使用如DRAM搭配PMEM成为未来数据中心的主流方案，但是如何快速识别热点数据并让其准确保持在DRAM中运行是影响性能的关键因素，这就要求系统具备快速识别热点数据的能力，并能动态跟踪捕获热点数据的变化，让其处于高性能的DRAM中，但是不幸的是，现有工具为达到一定的准确度，通常会耗费大量的时间，并引入额外的overhead，造成性能回退。 - -此外服务器硬件架构的快速迭代，cpu核数越来越多，numa节点也越来越多，例如amd服务器numa node数目达到8个，arm服务器飞腾s2500 numa节点达到16个，跨numa节点访存带来的性能影响日益突出，如何低开销高效的识别出跨numa热点数据，并优化之，对于提升系统服务质量，有着重要的意义。 - -## datop：轻量级靶向热点内存扫描工具 -### 热点扫描原理及策略 -在内存领域，对内存进行优化其实依靠预测内存的行为而做的决策，但是能够高效准确的预测内存的走势，其实是非常困难的，此外内存的策略优化对于用户来说，是不透明的，因此现有内存领域的各种策略机制，在实际生产环境中，并未取得很好的效果，也正是基于这些原因，社区推出了一种新的内存调控机制DAMON（Data Access Monitor），它试图让向用户展示内存的动作行为，让用户可根据这些行为相应的调整内存管理策略。 - -### 三大chunks -服务器现有硬件能支持非常巨大的地址空间，内存容量动不动达到几个T的大小，工作负载耗用内存几个G也是很普遍的事，随机毫无规律的划分地址空间可肯定是不可取的，并且在实际使用中，只有小部分区域被实际映射到内存并被访问，DAMON通过分析和论证，先将地址分为三大chunks，这三个chunks区域之间的空隙是给定地址空间中两个最大的未映射区域。 - -图1： -![](../assets/datop1.png) -在大多数情况下，两个最大的未映射区域是堆与最上层mmap() ed区域之间的空隙，以及最下层mmap() ed区域与堆栈之间的空隙, 因为这些间隙在通常的地址空间中是非常大的，排除这些就足够了,所以针对一个工作负载而言，DAMON只需要监控一下这些区域就足够了, 此外，随着工作负载的运行，映射区域发生变化，例如部分最大ummaped区域易主，所以damon设置了一个update周期，去周期性检测这些三大chunks的有效性，重新查找有效的三大chunks，并和现有监测得区域进行对比，删减或者增加。 - -### region拆分与合并 -在获取三大chunks后，damon会按照设定规则，去将这三个chuns划分为不均等的若干分regions, 如下图2所示： - -图2： -![](../assets/datop2.png) - -这些regions后面会随着热点频率去动态调整，进行拆分或者合并操作，其算法原理大致如下： - -拆分原则: - -- 大于等于2倍 DAMON_MIN_REGION才能拆分； -- 拆分region的size不能小于DAMON_MIN_REGION； -- region可以拆分为3个，当regions个数大于max_nr_regions的2/3后，降低拆分个数，由3变2； -- region个数必须保持在min_nr_regions和max_nr_regions范围内； -合并原则: - -- 两合并的regions必须收尾地址相等； -- 两者热点统计值之差必须小于设定阈值范围内； -### region采样与热点统计 -“trace page access bit”技术作为跟踪热点内存通用那就的技术手段，被业界广泛使用，但是该技术有一个固有的缺陷，那就是随着工作负载耗用内存增加，自身带来的开销和跟踪质量都会变糟，而damon通过region划分， 再结合空间采样方式良好的解决了该缺陷：假设一个region中，所有page都有相同的访问模式，这样的话，只需要监控一个page就够了。这样一来，在每个region里面，会随机选择一个page，在bitmap中把它对应的“accessed（访问过）”bit先清零，然后时不时地检查一下，如果这个page被访问过了，那么就算作这个region都被访问过了，它不是监视所有的页面，而是只监视reigon里面随机抽取的一个页面，该页面在某个采样时刻代表着这个region, 并将该值记录下来， 随着采样的不断进行，该region的热点就被统计下来了。 -``` -void check_access(region ∗ r) { - if (!r−>sampled_page) - goto next ; - if (accessed(r−>sampled_page) ) - r−>nr_accesses++; - next: - r−>sampled_page = rand_page(r->sampled_page); - clear_accessed(r−>sampled_page); -} -``` -上述伪代码只是介绍其采样和统计实现方法，其更复杂的逻辑处理关系，例如region合并和拆分后nr_access的值处理，以及nr_access周期性清零等本文不再介绍，有兴趣的读者可以依据damon实现源码自行分析。 - -### numa仿真实现 -社区damon能有有效的识别工作负载内存的冷热情况，但是对于工作负载内存跨numa访存这块，是无法做出判断的， 然而在实际业务中，跨numa访问造成的性能衰退问题真实存在，尤其是现今服务硬件多numa架构numa数目越来越多，正式基于以上原因，我们丰富了damon kernel部分代码，增加了内存numa访存情况。 - -和热点统计一样，numa仿真不会统计region中所有page的跨numa访问情况，而是利用damon空间采样方式，将damon获取的page在clear了access bit后，将其设置为pte none. -``` -void check_numa(region ∗ r) { - if (!r−>sampled_page) - goto next ; - if (local_numa_node(r−>sampled_page) ) - r−>nr_local++; - else - r->nr_remote++; - next: - r−>sampled_page = rand_page(r->sampled_page); - set_page_none(r−>sampled_page); -} -``` - -同样该部分伪代码只是介绍其numa基本实现，在实际中我们需要考虑pte处于swap，和page属于大页的情况，此外在pte设置为none后，会造成再次访问该page时发生page_fault和tlb miss的情况，我们测试发现，在某些频繁访问某块内存的工作负载中，造成一定的性能损耗，所以在实际使用中，我们增加了numa仿真开关，需要的时候去开启该功能。 - -### 小结 -基于上述几小节对damon以及numa仿真在kernel部分的实现机制的介绍，让我们对datop工具的实现原理有了清楚的认识，datop包括内核态部分和用户态部分，用户态可以通过perf调用功能，将内核态通过trace统计的热点信息捕获，并排序显示出来，详细调用流程入下图3显示。 - -图3： -![](../assets/datop3.png) - -在用户态，DATOP通过trace_event、damon dbgfs、以及numa switch接口和内核进行交互： - -蓝色绘制线部分：该部分是和用户态显示的核心， 通过内核kdamond线程将采样统计的相关值传递给trace接口， 用户态通过trace_event方式获取region区域热点信息，包括区域大小，access统计，进程信息以及跨numa统计等，最终通过窗口向用户展示。 - -黑色绘制线部分：该部分用于控制内核态线程kdamond的相关行为，通过damon dbfs接口，用于设置采样频率，更新周期，region个数划分，监控进程配置，kdamond线程的开启和关闭等。 - -绿色绘制线部分用于设定numa仿真功能的开启和关闭，此功能针对支持多numa的场景。 - -红色绘制线部分是热点工具的核心执行单元，用户态通过dbgfs接口开启监控后，kdamond线程被创建， 首先会查找被监控进程的三大chunks, 找到后，按照damon dbgfs接口设定的region个数方范围，对其进行拆分，此后按照设定好的采样频率进入周期性循环工作，直到被监控进程停止运行或用户操作dbgfs接口，停止监控，在周期性循环中，会对region热点进行随机采样并统计，此外还判定用户是否开启numa仿真功能，若开启还会对region跨numa情况进行统计，处理完成后，会更新采样结果，并通过trace event传递给用户，以上操作完成后，会依据kdamond线程运行时间，并在指定周期内，通过热点统计值对region进行拆分和合并操作，此外在更长的周期到来后，还会从新检查chunks的准确性，并按多加少减原则，修改region，以此保证热点内存跟踪的实时性和准确性。 - -至此DATOP技术实现原理介绍完毕，后面会进入介绍使用和数据测试方面的介绍。 - -## 使用 -在龙蜥社区[clouk-kernel](https://gitee.com/anolis/cloud-kernel) 5.10版本内核支持damon代码以及自研的numa仿真部分代码，结合开源的用户态工具[datop工具源码](https://gitee.com/anolis/data-profile-tools.git) 就可以运行起来了，datop工具支持单、多进程以及cgroup粒度内存热点监控以及跨numa访存监控 两种方式，详细使用可以参考源码readme部分。 -此外也可以参考龙蜥社区关于datop介绍的视频[轻量级靶向内存热点扫描工具介绍与入门](https://openanolis.cn/video/528538652696158417) - -目前龙蜥社区已整合datop工具到镜像中，你可以通过[datop rpm anolis a23](https://gitee.com/src-anolis-sig/data-profile-tools/tree/a23/) 在龙蜥社区5.10上构建完成的rpm包，此外也可以通过yum方式对datop工具进行安装。 -``` c -yum install datop -``` - -## 测试说明 -关于测试情况，可以参考先前文档介绍： -[datop测试情况介绍](https://openanolis.cn/sig/Cloud-Kernel/doc/721476494878572689) - -## 参考 -https://sjp38.github.io/post/damon/ -[Memory-management optimization with DAMON](https://lwn.net/Articles/812707/) - -[Using DAMON for proactive reclaim](https://lwn.net/Articles/863753/) - -[DAMON Extended To Offer Physical Memory Address Space Monitoring](https://www.phoronix.com/news/DAMON-Physical-Monitoring) - -[Proactively reclaiming idle memory](https://lwn.net/Articles/787611/) - -[damon用户态工具damo](https://github.com/awslabs/damo) - - -阿斯顿发斯蒂芬 \ No newline at end of file diff --git a/PRODUCT_DOCS/test/test4.md b/PRODUCT_DOCS/test/test4.md deleted file mode 100644 index 7b1213c9b0b5448f5d202d9d9b0ba22739bd708c..0000000000000000000000000000000000000000 --- a/PRODUCT_DOCS/test/test4.md +++ /dev/null @@ -1,118 +0,0 @@ -*斜体文字* - -_斜体文字_ - -**粗体文字** - -__粗体文字__ - -***粗斜体文字*** - -___粗斜体文字___ - -*** -* * * -****** -- - - ------- - -~~删除线~~ - -带下划线文本 - -# 一级标题 - -## 二级标题 - -### 三级标题 - -#### 四级标题 - -##### 五级标题 - -###### 六级标题 -[链接]（https://image.baidu.com/） -![绝对路径](http://gips0.baidu.com/it/u=1690853528,2506870245&fm=3028&app=3028&f=JPEG&fmt=auto?w=1024&h=1024) - -![相对路径](../assets/datop1.png) - -
哈哈哈
- -
- 图片名称 -
- -图片名称 - -* 第一项 -* 第二项 -* 第三项 - -+ 第一项 -+ 第二项 -+ 第三项 - -- 第一项 -- 第二项 -- 第三项 -1. 第一项 -2. 第二项 -3. 第三项 -4. 第一项： - - 第一项嵌套的第一个元素 - - 第一项嵌套的第二个元素 -5. 第二项： - - 第二项嵌套的第一个元素 - - 第二项嵌套的第二个元素 - 1) ASDF - 2) ASDF - 3) ASDFDD - 1) SDFGSDFG - 2) SDFGSDFG - 1) FGSDFG - 1) SDFGSDFGSDFG - 2) SDFGDSFG - -水平线： - - -1) test -2) ttdd -3) dddfasdf - 1) asdfas - 2) asdf - 1) asdf - 2) asdf - 1) asdfsdfds - 2) asdfsdaf - ---- -带反引号的“内联代码” -``` -# 代码块 -print '3 个反引号或' -print '缩进 4 个空格' -``` - -> 区块引用 -> Markdown教程 -> 学的不仅是技术更是梦想 - -HCT密码计算套件的目录结构如下： -阿斯顿法师打发斯蒂芬 -44444444444444444444444444444444444444444444444444444 -hygon-devkit/ - - ├─ hct - ├──pkg - │ ├── hct_1.0.0.20230224_rc - │ ├── hct_1.0.1.20230512_rc - │ └── hct_1.1.0.20230730_rc - │ - └── README.md - -\* pkg目录：内含各版本hct密码计算套件。 - -\* README.md文件：有关HCT的简单情况。 -阿斯顿发斯蒂芬 -阿斯顿发斯蒂芬 \ No newline at end of file diff --git a/PRODUCT_DOCS/test1/test1.md b/PRODUCT_DOCS/test1/test1.md deleted file mode 100644 index 724cb7b756f3dfe9aab1939efee70a5e60cfed6d..0000000000000000000000000000000000000000 --- a/PRODUCT_DOCS/test1/test1.md +++ /dev/null @@ -1,6 +0,0 @@ -# test -__test2__ -## testlib -随便写写 - -这个也得试试 \ No newline at end of file diff --git a/PRODUCT_DOCS/test2/test b/PRODUCT_DOCS/test2/test deleted file mode 100644 index ecc893c8fc38f7acad9e230fb2ca9a12e3ff38a7..0000000000000000000000000000000000000000 --- a/PRODUCT_DOCS/test2/test +++ /dev/null @@ -1,2 +0,0 @@ -222222 -又是一个test \ No newline at end of file diff --git a/PRODUCT_DOCS/zhongjie/test/test1.md b/PRODUCT_DOCS/zhongjie/test/test1.md deleted file mode 100644 index 9734cc11742cea8b5c36257172ffd8325fbe19b3..0000000000000000000000000000000000000000 --- a/PRODUCT_DOCS/zhongjie/test/test1.md +++ /dev/null @@ -1 +0,0 @@ -test111 \ No newline at end of file diff --git a/TECHNOLOGY_DOCS/GITEE/302-join-os-package-build.md b/TECHNOLOGY_DOCS/GITEE/302-join-os-package-build.md deleted file mode 100644 index 4cd28a3c66a71ef5565a568f6d0abe93aba331d5..0000000000000000000000000000000000000000 --- a/TECHNOLOGY_DOCS/GITEE/302-join-os-package-build.md +++ /dev/null @@ -1 +0,0 @@ -# 参与发行版核心软件包的构建 diff --git a/TECHNOLOGY_DOCS/GITEE/303-join-kernel-developing.md b/TECHNOLOGY_DOCS/GITEE/303-join-kernel-developing.md deleted file mode 100644 index d155e9b40cfcaed96d4cc4c96fae02d47ff2ac14..0000000000000000000000000000000000000000 --- a/TECHNOLOGY_DOCS/GITEE/303-join-kernel-developing.md +++ /dev/null @@ -1 +0,0 @@ -# 参与龙蜥内核的开发工作 diff --git a/TECHNOLOGY_DOCS/GITEE/304-package-introduction-and-management-principles.md b/TECHNOLOGY_DOCS/GITEE/304-package-introduction-and-management-principles.md deleted file mode 100644 index 5c6d46a4071a5fcb2918a75cc9d6379e6cbba014..0000000000000000000000000000000000000000 --- a/TECHNOLOGY_DOCS/GITEE/304-package-introduction-and-management-principles.md +++ /dev/null @@ -1,275 +0,0 @@ -# 304 龙蜥社区软件包引入和管理原则 - - -## 1. 综述 -### 1.1 文档范围 -本文档涵盖： - -- 龙蜥社区产品发布 SIG 成员在引入或维护 RPM 软件包时需遵循的准入原则及操作流程； -- 龙蜥社区开发者及各 SIG 成员将 RPM 引入 Anolis OS 发行版时需遵循的准入原则及操作流程。 - -本文档不涵盖： - -- 源码引入原则及操作流程。源码引入到龙蜥社区是另外的话题，需要单独向龙蜥社区技术委员会申请； -- 软件包引入规则的原理解析； -- 软件包引入时 RPM SPEC 的编写细节。 - -本文档的维护主体为**龙蜥社区技术委员会**，文档定稿或重大修改均需报请技术委员会审议，通过后施行。 - - -### 1.2 术语定义 - -在本文描述中，软件包代码在仓库中的组织形式分为两种，分别为「source tree」和「rpm tree」。 - -- 「**source tree**」 是指项目源码本身，在 Gitee 中以源码协作开发的方式维护，并按照软件自身研发节奏发布对应的 release，供其他社区或者爱好者进行下载使用，本文档不涉及 source tree 的组织与管理； -- 「**rpm tree**」 是用于龙蜥社区构建发行版和 SIG 组构建产品对应的软件包的代码树，通常包含 rpm spec 文件 + 包含源码的 tarball，可用于后续构建和发布。这部分软件按照软件的成熟度分别放在对应不同的 Gitee 仓库。 - - -### 1.3 修订记录 - -| **时间** | **作者** | **版本** | **描述信息** | -| --- | --- | --- | --- | -| 2022/08/31 | happy_orange, caspar | v1.0 | 初始版本 | -| 2022/11/03 | happy_orange | v1.1 | 修正软件选型的原则 | -| 2023/06/13 | happy_orange | v1.2 | 在软件包引入的基本原则中增加依赖软件的要求 | -| 2023/08/13 | happy_orange | v1.3 | 增加软件维护责任说明、闭源软件引入规范和流程 | - - -## 2. 软件包管理基础设施介绍 - -龙蜥社区使用 Gitee 管理 Anolis OS 发行版及所有 SIG 组的软件包代码，统一放在 [https://gitee.com/openanolis]() 组织下。 - - - -### 2.1 软件包在代码仓库的位置 - -此处展示使用较为频繁的几个软件包仓库的信息： - -| **类别** | **仓库名称** | **仓库地址** | **仓库介绍** | -| --- | --- | --- | --- | -| source tree | anolis | [https://gitee.com/anolis](https://gitee.com/anolis) | 存放龙蜥社区所有项目的 source tree，本文不涉及。 | -| rpm tree | src-anolis-os | [https://gitee.com/src-anolis-os](https://gitee.com/src-anolis-os) | 存放 Anolis OS 发行版默认 RPM 打包代码 | -| | src-anolis-sig | [https://gitee.com/src-anolis-sig](https://gitee.com/src-anolis-sig) | 存放龙蜥社区各 SIG RPM 打包代码 | -| | src-anolis-xxx | | 其他特殊 SIG 的 RPM 打包代码 | - - -### 2.2 代码分支管理 -对于 rpm tree，每个软件仓库会通过特定分支进行进一步统一管理，确保不同的 OS 版本都有对应分支可映射；在初始化仓库时，应该建立对应版本的分支，后续将代码提交 PR 通过 review 后合入到对应分支上。 - -| **分支名称** | **介绍** | -| --- | --- | -| **master**, **main** | 默认都为空，用于初始化其他发行版对应的分支，禁止使用该分支管理代码。 | -| **aX** (X 为不带任何后缀的大版本数字），如 a7, a8, a23, a25 等 | Anolis OS X 版本的主线分支。 | -| **aX.Y** (X 为大版本数字，Y 为对应小版本数字），如 a8.2, a8.6 等 | Anolis OS X 以前发布过的 Y 小版本对应的分支，最新的主线分支开出后，之前的主线分支则重命名为形如 aX.Y 的形式。 | -| **aX-{module名}-stream-{版本名称}** 或
**aX.Y-{module名}-stream-{版本名称}** | Anolis OS X 或者 X.Y 版本对应的 module 的模块化版本分支。 | - - - -## 3. 软件包引入 -软件包引入由申请人发起，申请人可以是产品发布 SIG 组成员，也可以是其他 SIG 组对应软件包的 owner（以下统一称为「软件包负责人」）。 - -### 3.1 软件包引入基本原则 -软件包负责人需明确软件包引入原则，不符合软件包引入原则的组件，不允许引入。软件包引入的原则包含三大原则： - -- 背景和用途：能给出引入背景和软件用途，并阐述带来的业务场景和价值 -- 软件维护责任：软件引入时，需要同时声明软件包的负责人，并承担起维护的责任，包括：修复 bugfix、修复 CVE、更新等动作 -- 引入责任规范：必须满足下面所有的引入要求，达到合规状态的软件才允许引入 - -**程度** | **要求项** | **补充说明** ---|--|-- -must | 软件包的内容必须遵守国家法律法规、遵守社会公序良俗 | -must | 软件包不允许存在合规、安全问题 | 例如：无 license 或 license 尚存在争议的软件 -must | 软件包能给出明确的 License，并且属于开源软件的白名单范围内 | [license 白名单](https://gitee.com/anolis/anolis-ci-test/blob/master/utils/license_check/white_black.xlsx) -must | 软件包在龙蜥社区的 rpm tree 中从未引入过，且软件命名规范，遵循上游社区命名方式 | 同一款软件只能存在 rpm tree 的其中一个仓，如有，后加的仓库应当合并到先有的仓库。例如：src-anolis-os 和 src-anolis-sig 不可以包含同名软件包 -must | 软件包对应的上游开源社区仍在运营，并在持续发布 release | 运营是指有代码提交、代码和入、issue解决等，代表上游社区的代码仓并没有被废弃 -must | 新引入软件需要遵循 follow upstream 模式，即 source.tag.gz 是来自上游开源社区的正式版本 | md5 值和上游相同，且选取版本为正式 release 版本 -must | 原则不允许引入其他二进制，需要从源码构建，生成对应的 rpm，如果需要引入二进制软件请参考闭源软件引入规范 | 如果对构建依赖版本多要求的（比如：依赖多个 kernel-devel 版本），则需要构建多次 - must | 软件包所需要的全部构建依赖和运行依赖必须已经存在，如果不存在，则必须按照同等规则先引入；如果已经存在，但是需要更新版本，则需要有完整评估，不能影响其他组件。 | 核心包和成熟包必须将构建依赖和安装依赖全部引入；
对于孵化期软件引入时，要求可以酌情降低，允许通过其他方式引入构建依赖和安装依赖;
Anolis OS 8 中允许使用 epel 仓库作为孵化期软件的构建依赖和所有软件的安装依赖，Anolis OS 23 没有 epel 仓库，不允许使用
Anolis OS 8 中如果有 epel 包转自维护，需要和自维护软件同等策略维护
在引入软件如果需要引入较多软件，并且有责任人进行长期维护，可以支持新增 group 或者 repo 的方式统一处理 - must | Anolis OS 8 中允许使用 epel 仓库 | 发行版团队的同学会定期巡逻 epel ，将 epel 的包列表与 Anolis OS 8 里面自维护软件的基线列表进行对比，如果发现 epel 高于基线列表，会发起告警并需要对应软件包的负责人进行处理。 - must | 软件维护策略：谁引入谁负责，同时需要负责引入该软件过程中的构建依赖和安装依赖软件。 | 当前构建依赖和安装依赖的构建由发行版团队进行看护，待 abs 功能完善后，支持由 sig 的主要 maintainer 自行决定构建和发布策略，但需要同时对发行版负责 -must | 同一个背景下引入的软件应该全部放到一个仓库中，不允许跨仓库存放。 | -must | 新引入的软件不允许对原有软件产生影响。 |比如：不能提供相同的能力，导致 repo 出现错误 -must | 软件包 owner 需要评估软件的运行平台，缺省默认全部支持，如果存在不支持的架构则需要额外声明 | 目前龙蜥社区支持列表为：x86_64、aarch64 和 loongarch64 -must | 软件引入时，优先引入 Anolis OS 23 版本，其次同步引入 Anolis OS 8 版本。 | 如果仅引入 Anolis 8，需要上 TC 会议说明背景和原因。 - - - -### 3.2 闭源软件引入规范 -闭源组件主要针对不想公开源码、仅公开二进制的场景，龙蜥社区允许这部分特殊软件通过闭源方式引入，并提供 epao-nonfree 仓库作为闭源组件的 repo 源公开使用。 -闭源组件除了需要满足上述 「[3.1 软件包引入原则](#31-软件包引入基本原则)」的基本原则外，还需要满足如下规范： - -**程度** | **要求项** | **详细说明** ---|--|-- -must | 确定来源方式，保证合法合规 | 来源分为两种：全自研闭源和二次开发闭源
1. 全部代码自研闭源。
全部代码自研闭源方式需要走二进制披露程序，公司内部组件请自行联系法务，如果由其他合作伙伴提供，则需要合作伙伴提供对应的许可证书和对应公司的闭源二进制发布许可证明，并向发行版同学提供许可证书；
2. 基于开源组件的二次开发闭源
基于开源组件的二次开发闭源方式，需要走公司内部二进制披露程序和开源代码扫描，查看原组件的 License 类型，并确定该 License 允许在二次开发后仅通过二进制的形式对外公开 | -must | 不能和现有开源组件发生冲突 | 1. 软件命名不能和现有组件相同，如果相同则需要重新定义。
2. 软件版本尽量要和现有版本保持一致，如遇到特殊情况需要额外说明选择不同软件版本的原因，并保证软件维护者快速响应 CVE 和功能问题。 -must | 保证安全可靠，经过充分的测试保障 | 1. 闭源软件引入过程中需要走假构建流程，即需要经历 CI 的测试，包括：安装、卸载、abi 检测、repo 的依赖关系检测等。
2. 闭源组件的运行依赖需要参照开源组件的运行依赖要求，运行依赖建议参照开源组件方式进行引入，同为闭源组件则应该先引入依赖部分的闭源组件。
3. 闭源组件需要有明确的维护周期，并在更新的过程中持续保持兼容和安全，即在其发展路线中需要给出 bugfix 、CVE、版本更新的预期节奏和更新频率。
4. 如果是基于开源组件二次开发，在开源组件的 cve 修复之后，该闭源组件的维护者也需要快速响应，修复对应的 cve。 - - - - -### 3.3 版本选型原则 - -龙蜥社区的软件选型主要围绕「分层分类」理论展开，根据软件包对操作系统发行版的重要程度，以及整体应用场景模块化程度，设立不同的选型原则。 - -- 优先级上参照「分层分类」理论中的分层思想，从层级优先级高的软件包开始重点制定和维护策略； -- 场景上参照「分层分类」理论中的分类思想，按应用场景维度分割，模块化地分批引入软件包； - -| **layer 序号** | **layer 名称** | **详细描述** | **选型规则** | -| --- | --- | --- | --- | -| layer-0 | 内核层 | 操作系统服务（内核） |
1. 跟随上游内核社区，选取社区成熟期 LTS 版本；
2. 选型需兼顾龙蜥社区 IHV 生态支持最完整的内核版本，降低硬件补丁回合成本；
3.选型需兼顾龙蜥理事成员单位向上游贡献重大特性较多的内核版本，降低特性回合成本；
4. 在一个 OS 版本内不发生大版本变更，仅采取 release 更新形式，以补丁形式合入。
| -| layer-1 | 核心层 | 核心工具、核心库、核心服务 |
1. 跟随上游社区，选取社区稳定版本或 LTS 版本；
2. 和硬件相关的组件选型时需兼顾龙蜥社区 IHV 生态支持最完整的版本，降低硬件补丁回合成本；
3. 在一个 OS 版本内主要版本不发生大版本变更，仅采取 release 更新形式，以补丁形式合入；
4. 原则上不允许同时引入多个版本（例如 libssh, libssh2 需要选择一个版本）。
| -| layer-2 | 系统层 | 系统工具、系统库、系统服务 |
1. 跟随上游社区，选取社区稳定版本或 LTS 版本；
2. 和硬件相关的组件选型时需兼顾龙蜥社区 IHV 生态支持最完整的版本，降低硬件补丁回合成本；
3. 在一个 OS 版本内主要版本不发生大版本变更，仅采取 release 更新形式，以补丁形式合入；
4. 原则上不允许同时引入多个版本（例如 libssh, libssh2 需要选择一个版本）。
| -| layer-3 | 应用层 | 应用工具、应用库、应用服务 |
1. 尽量选取正式发布的最新版本；
2. 允许在一个 OS 版本内发生 version 变更，但要对影响范围整体评估清楚，必须通过**兼容性验证**；
3. 原则上不允许同时引入多个版本。
4. 自研 module 包可以采用 module 模式进行管理，保障单一大版本演进过程的应用软件兼容性 | -| layer-4 | 应用场景 | 数据库、云原生、大数据、桌面等应用场景 |
1. 优先选择最新的，其次如果最新的版本带来不兼容（对其他软件产生影响）的问题，则可以选取次新版本；
2. 允许支持某款软件存在多个版本，但需要由需求驱动，比如：tomcat 7、tomcat 8、tomcat 9等。
3. 具体业务涉及的软件版本可以由对应负责人决策，不做过多要求。
| - - -### 3.4 SPEC 规范 -详细规范请参阅 [Anolis OS 23 spec 规范](/articles/305-module-and-checklist-of-spec.md)。
下列情形需严格遵守该规范编写 SPEC 文件： - -- Anolis OS 23 及以后的发行版引入的所有软件包； -- Anolis OS 7, Anolis OS 8 中新引入的软件包。 - -下列情形可参考本规范，并不强制执行： -- Anolis OS 7 和 Anolis OS 8 中现存的软件包。 - - - -### 3.5 开源软件引入流程 -1. **引入条件审查**：软件包负责人需根据 「[3.1 软件包引入原则](#31-软件包引入基本原则)」 和 「[3.2 版本选型原则](#32-闭源软件引入规范)」所载明的规范要求，明确软件包的代码符合要求、版本选型符合规范，同时明确软件包的演进和维护路线。 -1. **提交软件包引入申请**：软件包引入涉及发行版基线变更，基线数据是通过社区的软件包集成项目 ([ospkg-list](https://gitee.com/anolis/ospkg-list)) 管理的。每一个软件包都需要通过 Pull Request 提交引入意向申请。该申请将由产品发布 SIG maintainer 负责审阅，必要时报请技术委员会成员审阅，如通过后则完成软件包基线数据的变更。 - 1. 如果软件包在 ospkg-list 里不存在，则需要参照「[附录1.1 软件包引入申请模板](#附录-11-软件包引入申请模板)」填写一个新的 `{package}.yaml`文件。申请通过后由产品发布 SIG maintainer 创建新的仓库和对应分支； - 1. 如果软件包在 ospkg-list 里已经存在，则无需提交新的 `{package}.yaml`，在现有软件包数据中添加新的字段即可。申请通过后由产品发布 SIG maintainer在现有仓库创建新的分支。 -1. **本地验证**：在本地进行软件包的构建和安装验证，保证基本功能正常。 -1. **提交软件包代码**：根据 「[305 SPEC 规范](../articles/305-module-and-checklist-of-spec.md)」制作符合要求的 rpm tree 代码，并提交 PR 到对应的软件包分支中。 -1. **完成引入:** 产品发布 SIG maintainer，必要时社区技术委员会指派成员，根据 review 规范审核对应的 PR，如通过后则完成软件包整体引入。其他 review 结果包括：打回修改，拒绝等。如拒绝则需给出明确的理由。 - - - -### 3.6 闭源软件引入流程 -1. **引入条件审查**：软件负责人根据「[3.2 闭源软件引入规范](#31-软件包引入基本原则)」所声明的规范要求，明确软件包的代码形式、License 符合规范，同时明确软件包的演进和维护路线。 -2. **联系法务人员，保证二进制开源合规**：软件维护者需要联系软件提供厂家的法务人员，一般要申请两个纰漏流程，包括二进制披露和开源代码合规扫描，完成流程审批。 -3. **提交软件包引入申请**：同 「[3.5 开源软件引入流程](#35-开源软件引入流程)」中的提交申请步骤相同，在 ([ospkg-list](https://gitee.com/anolis/ospkg-list)) 发起申请，按照模版填写清楚背景（包括闭源原因）、收益、维护者、维护方式、License 类型等基本信息。 -4. **建立代码仓库和分支**：发行版同学在接收 ospkg-list 申请之后，进行评估，评估通过之后，会进行建立代码仓库、建立分支操作。 -5. **提交代码**：软件维护 owner 按照 [308 闭源软件集成样例](../articles/308-example-of-epao-nonfree-package.md) 将二进制提交，并发起 pr，等待门禁 CI 的运行结果 -6. **合并代码和正式构建**： 待 maintainer 审核通过后，由发行版同学负责正式构建和发布。 -7. **用户安装使用**：待软件发布到 epao-nonfree 源之后，需要先安装 anolis-epao-nonfree-release 包，再通过 yum install 方式安装闭源组件。 - -## 4. 软件包构建 -软件包构建从构建目的角度可以划分为两种：自验证构建和正式构建。 - - - -### 4.1 自验证构建 -该过程为开发者自行在本地或模拟环境中对软件进行构建，以验证软件包本身的构建能力或产出测试包供后续测试。目前推荐的方式有两种： - -- 本地通过 mock 机制构建，参考《[Anolis OS 8 软件包本地构建 · 语雀](https://www.yuque.com/anolis-docs/kbase/cvy9g3?view=doc_embed)》一文； -- 通过 Anolis Build System (ABS) 提供的个人工作空间机制进行自定义构建，可以参考[《使用ABS平台轻松胜任Anolis OS开发工作》](../articles/208-how-to-build-package-via-ABS.md) 一文的内容，进行构建。 -- 构建过程中遇到的问题参考 「[306 rpmbuild 构建指导手册](../articles/306-instruction-manual-of-rpmbuild.md)」 - - -### 4.2 正式构建 -正式构建的产物将会发布到对应的 Anolis OS 发行版本中，因此需要慎重操作。正式构建操作需要通过命令行操作，并且需要提前获得相关 token，请联系龙蜥社区发 -布小组 maintainer 获取相关 token。 - - - -## 5. 软件包发布与变更 - - -### 5.1 软件包发布原则 -软件包发布指的是将通过正式构建流程生成的二进制推送到镜像 YUM repo 中。发布时会根据 ospkg-list 工具中的软件包基线数据信息，推送到对应的 YUM repo 中。
软件包经过正式构建得到 RPM 产物后，并不能直接发布，需要经过 abs 系统集成的 CI 流程后，由产品发布 SIG maintainer 执行软件包签名，之后推送 YUM repo 并生成发布单(Errata)。 - -### 5.2 软件成熟度划分和变更流程 - -OpenAnolis 龙蜥社区中将所有的软件划分成三个阶段：系统包、成熟包、孵化包。 - -| 阶段名称 | 阶段介绍 | 维护主体 | 变更流程 | 补充 | -| -------- | ------------------------------------------------------------ | ------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | -| 系统包 | Anolis OS 中 Lay0 - Lay2 对应的核心软件范围，不允许随意更改。 | 发行版团队和内核团队 | 需要 TC 会议进行评审，评审通过后，即可引入。 | | -| 成熟包 | Anolis OS 中 Lay3 - Lay4 对应的稳定应用软件范围，由维护主体决定更新策略，支持按需更新。 | 发行版团队和龙蜥社区 sig | ospkg-list 发起转正请求，并提供转正材料，通过转正评审即可引入。 | 转正材料：软件的维护责任心和维护计划、软件的特性列表、引入软件的必要性、软件的真实使用场景和客户、软件依赖范围是否变更、 CI 检测的结果、稳定性或 CVE 相关信息等。 | -| 孵化包 | 龙蜥社区 SIG 和 社区开发爱好者新引入的软件，由维护主体决定更新策略，支持快速迭代。 | 龙蜥社区 sig 和开发爱好者 | ospkg-list 发起软件引入申请并通过 | | - -### 5.3 Anolis OS 软件包仓库结构 - -根据 「[3.1 软件包引入原则](#31-软件包引入基本原则)」 和 「[5.2 软件成熟度划分和变更流程](#52-软件成熟度划分和变更流程)」中的分层机制，OpenAnolis 龙蜥社区将所有软件按照如下 [YUM 仓库](https://mirrors.openanolis.cn/anolis/) 进行管理，分为三大类：系统包、成熟包、孵化包。 - -| 仓库名称 | 阶段 | 仓库介绍 | 仓库分层信息 | 仓库维护 owner | ISO 包含 | 仓库默认状态 | Anolis OS 8 仓库范围 | Anolis OS 23 仓库范围 | -| ---------------- | ------ | ----------------------------------------- | -------------------------------------------- | -------------------------- | --------- | ----------------- | -------------------- | --------------------- | -| BaseOS | 核心包 | Anolis OS 8 中的核心软件 | Lay 0 - Lay2 的全量软件部分 Lay 3 软件 | 发行版团队 | 是 | ✅ 预装
✅ 使能 | 有 | | -| AppStream | 成熟包 | Anolis OS 8 中的稳定的开源应用库和应用软件 | Lay 3 软件 | 发行版团队 | 是 | ✅ 预装
✅ 使能 | 有 | | -| os | 成熟包 | Anolis OS 23 中的 iso 中的全部组件，包括核心组件和应用组件等 | Lay 0 - Lay 3 软件 | 发行版团队 | 是 | ✅ 预装
✅ 使能 | 有 | -| PowerTools | 成熟包 | 使用广泛的应用类软件 | Lay 3 软件 | 发行版团队 | 否 | ✅ 预装
✅ 使能 | 有 | | -| Extras | 成熟包 | Anolis OS release 组件 | Lay 3 软件 | 发行版团队 | 否 | ✅ 预装
✅ 使能 | 有 | | -| kernel-x | 成熟包 | 存放 x 版本的 kernel 包和该内核相关的组件 | Lay 3 软件 | kernel sig + 发行版团队 | 是 | ❌ 预装
❌ 使能 | 有 | 有 | -| Plus | 成熟包 | 通过社区 sig 运行较为成熟的软件 | Lay 3 软件 | 社区 sig | 是 | ❌ 预装
❌ 使能 | 有 | | -| DDE | 成熟包 | DDE sig 包含的桌面相关的软件 | Lay 4 软件 | 社区 sig | 否 | ❌ 预装
❌ 使能 | 有 | | -| HighAvailability | 成熟包 | 高性能 sig 包含的软件 | Lay 4 软件 | 社区 sig | 否 | ❌ 预装
❌ 使能 | 有 | | -| Epao | 孵化包 | 孵化阶段的所有开源软件 | | 社区 sig 和 社区开发爱好者 | 否 | ❌ 预装
❌ 使能 | 有 | 有 | -| Epao-nonfree | 孵化包 | 所有闭源组件 | | 社区 sig 和 社区开发爱好者 | 否 | ❌ 预装
❌ 使能 | 有 | 有 | - - - -### 5.4 软件包发布流程 - -1. 经过正式构建得到候选发布(release candidate)包，abs 自动执行集成的 CI 流程，如未自动执行，则可在 abs 系统手工触发； -1. 通过所有 CI 测试项，或手工确认失败项无影响后，则达到发布条件。在 [Bugzilla 平台](https://bugzilla.openanolis.cn/enter_bug.cgi?classification=Anolis%20OS) 提交软件包发布需求，模板参考「[附录 1.3 软件包发布需求模板](#附录-13-软件包发布需求模板)」；同时需填写发布单(Errata)，如有多个软件包，则只需填写一个发布单即可，模板参考「附录 1.4 发布单模板」。 -1. 产品发布 SIG maintainer 确认通过发布需求，分别执行软件包签名、推送 YUM repo、生成发布单操作，如软件包达到系统包级别，则还需额外更新镜像 comps 文件。 - - -## 6. 软件包删除 -当某些开源软件不再符合 OpenAnolis 的规范时，需要将其从社区中删除。目前已知条件如下，持续更新： - -| **序号** | **分类** | **条件** | -| --- | --- | --- | -| 1 | 版权 | 软件的版权信息发生变更，如：license 存在争议、转商用等 | -| 2 | 代码风险 | 源码中存在恶意代码或者安全隐患，且无法修复或上游社区反馈不修复 | -| 3 | | 源码中存在争议风险，如：地区命名、民族习俗等 | -| 4 | 软件演进 | 开源社区不再进行维护，持续长时间无任何提交和 bug 讨论，考虑退出 | -| 5 | | 软件落后，存在其他同类软件替代 | -| 6 | | 功能不再被需要，可以无影响删除 | - - -## 附录1 - -### 附录 1.1 软件包引入申请模板 -```yaml -name: my_packages -repository: https://gitee.com/src-anolis-sig/my_package -summary: a short description -rpm_owner: anolis-bot -branches: -- name: a8 - repo: epao - maturity: rawhide -- name: a23 - repo: epao - maturity: rawhide -``` - -### 附录 1.2 社区重点生态应用场景 - -- 数据库 -- 云原生 -- Web Server - - -### 附录 1.3 软件包发布需求模板 - -> 申请发布 -> 1. 背景 -> 必填: 简单描述需求背景, 有必要可以提供相关公共链接 -> 2. 用户故事 ->必填: 说明用户, 业务/应用场景, 获得结果/收益, 价值/竞争力/优势等 -> 3. 重要性/优先级 ->选填: 说明该需求的重要程度, 优先级, 紧迫性等 -> 4. 目标/计划 ->选填: 说明该需求目标版本或预期日期等 -> 5. 依赖/影响 ->选填: 说明该需求开发, 测试相关依赖信息及工作量估计 -> 6. 验收标准 ->选填: 说明交付物, 预期效果等 - - -### 附录 1.4 发布单模板 -> - diff --git a/TECHNOLOGY_DOCS/GITEE/305-module-and-checklist-of-spec.md b/TECHNOLOGY_DOCS/GITEE/305-module-and-checklist-of-spec.md deleted file mode 100644 index d2a9f3106d5fdd7c1634a918b611a49d3f4c9d45..0000000000000000000000000000000000000000 --- a/TECHNOLOGY_DOCS/GITEE/305-module-and-checklist-of-spec.md +++ /dev/null @@ -1,335 +0,0 @@ -# 305 SPEC 模版和 checklist - -## 1 背景 -本文档规定龙蜥社区 RPM Tree 组织规范和 SPEC File 写作规范。 -适用范围： - -1. Anolis OS 自研的软件包； -1. Anolis 23 及以后的发行版所有的软件包； - -总体原则： - -1. 简洁、可阅读、易维护 -1. 统一龙蜥标签 - -**修订记录** - -| **时间** | **版本** | **作者** | **备注** | -| --- | --- | --- | --- | -| 2022.2.10 | v1.0 | [@林生](https://gitee.com/forrest_ly) | 初始版本 | -| 2022.3.31 | v1.1 | [@伊和](https://gitee.com/yueeranna) | 添加规范 | -| 2022.4.20 | v1.2 | [@伊和](https://gitee.com/yueeranna) | 添加 epoch 版本号说明 | -| 2022.8.3 | v1.3 | [@橘悦](https://gitee.com/happy_orange)| 新增模版和 checklist | -| 2022.11.03 | v1.4 | [@橘悦](https://gitee.com/happy_orange)| 增加 abi 和 api 的能力 | -| 2022.11.30 | v1.5 | [@橘悦](https://gitee.com/happy_orange)| 修改 python 类软件的规范 | -| 2023.2.7 | v1.4 | [@橘悦](https://gitee.com/happy_orange) | 增加 Requires 的介绍并修改 doc 包的依赖关系 | - -## 2 SPEC File 写作规范 -### 2.1 spec 基础模版 - -spec 基础模版，可以使用 rpmdev-newspec 命令生成。 -``` -%define anolis_release 1 -#Global macro/variable 定义 - -Name: package -Version: 1.0.0 -Release: %{anolis_release}%{?dist} -Summary: Library providing xxx -License: LBPLv2+ and MIT -URL: https://github.com/package -Source0: https://github.com/package/archive/%{name}-%{version}.tar.gz -Source1: temple.conf - -Patch0: bugfix-xxx-yyy.patch - -BuildRequires: cmake -BuildRequires: gcc -BuildRequires: gcc-c++ - -Requires: glibc - -%description -Library providing xxx and xxx. - -%package devel -Summary: Development files for %{name} -Requires: %{name} = %{version}-%{release} - -%description devel -The %{name}-devel package contains development files for %{name}. - -%package -n python3-%{name} -%{?python_provide:%python_provide python3-%{name}} -Summary: Python 3 bindings for the %{name} library. -BuildRequires: python3-devel python3-setuptools -Requires: %{name} = %{version}-%{release} - -%description -n python3-%{name} -python 3 bindings for the %{name} library. - -%package doc -Summary: Documentation files for %{name} -Requires: %{name} = %{EVR} -BuildArch: noarch - -%description doc -The %{name}-doc package contains documentation files for %{name}. - - -%prep -%autosetup -n %{name}-%{version} -p1 - - -%build -%configure -%make_build - - -%install -%make_install -# 下面两行按需添加，当前仅为样例 -mkdir -p %{buildroot}/%{prefix}/%{name} -install -m 0644 -p %{SOURCE1} %{buildroot}/%{prefix}/%{name} - -%check -%make test - -%files -%license COPYTRING -%{_bindir}/%{name} -%{_libdir}/%{name}.so.* - -%files devel -%doc example -%{_libdir}/%{name}.so -%{_libdir}/pkgconfig/%{name}.pc -%{_includedir}/%{name}/ - -%files -n python3-%{name} -%{python3_sitearch}/%{name}/ - -%files doc -%doc README.md AUTHORS ChangLog NEWS TODO - - -%changelog -- Wed Aug 03 2022 happy_orange - 1.0.0-1 -- Init package from upstream -``` - -### 2.2 纯 python 类 spec 模版 - -由于 python 类软件比较多，额外对外提供 python 类软件的 spec 模版。 -``` -%define anolis_release 1 -%global pypi_name package_real_name -%global debug_package %{nil} - -Name: python-%{pypi_name} -Version: 0.1.0 -Release: %{anolis_release}%{?dist} -Summary: xxxx package for Python - -License: MIT -URL: https://sourceforge.net/projects/%{pypi_name} -Source0: https://sourceforge.net/%{pypi_name}/code/%{pypi_name}-%{version}.tar.gz - -# python package only need to build in noarch. -BuildArch: noarch - -%description -xxxx package for Python - -%package -n python3-%{pypi_name} -Summary: YAML 1.2 loader/dumper package for Python -BuildRequires: python3-devel -BuildRequires: python3-setuptools -# For tests -BuildRequires: python3-pytest -Requires: python3-setuptools -%{?python_provide:%python_provide python3-%{pypi_name}} - -%description -n python3-%{pypi_name} -xxxx package for Python - -%package -n python3-%{pypi_name}-doc -Summary: doc files for python3-%{pypi_name} -Requires: python3-%{pypi_name} = %{EVR} - -%description -n python3-%{pypi_name}-doc -doc files for python3-%{pypi_name} - - -%prep -%autosetup -n %{pypi_name}-%{version} -p1 -rm -rf %{pypi_name}.egg-info - - -%build -%py3_build - - -%install -%py3_install - - -%check -%pytest - - -%files -n python3-%{pypi_name} -%license LICENSE -%{python3_sitelib}/%{pypi_name} -%{python3_sitelib}/%{pypi_name}-%{version}-*.pth -%{python3_sitelib}/%{pypi_name}-%{version}-*.egg-info - -%files -n python3-%{pypi_name}-doc -%doc README.rst - -%changelog -* Mon Jul 25 2022 happy_orange - 0.1.0-1 -- Init pacakge from upstream -``` - -### 2.3 rpm 增加 abi 和 api 信息 - -在 anolis 23 版本中额外支持在 rpm 中分别对 so 文件和 bin 文件增加 abi 和 api 信息，下面描述如何进行使用。 - -- 使用规则： - - 在 %install 阶段使用 `%generate_compatibility_deps` 生成 abi/api 文件 - - abi/api 文件默认都存在放在 `%{abidir}` 中 - - abi 文件需要和 so 文件一起打包 - - api 文件需要和 bin 文件一起打包 - - 需要通过`%dir %{abidir}`的方式增加路径定义，否则会造成卸载残留 - - 需要根据文件列表和依赖关系共同决定`%dir %{abidir}` 的定义位置，放置在依赖树中最底层的包内，常见情况如下： - - 如果只有单个 rpm ，则将路径定义增加到此 rpm 中； - - 如果有多个 rpm，但是 abi/api 文件仅存在一个 rpm 内，则将路径定义增加到此 rpm 内； - - 如果多个子包中都包含 abi/api 文件，并且这些子包之间是独立的，没有依赖关系，如果有主包，且都依赖主包，则将路径定义增加到主包内； - - 如果多个子包中都包含 abi/api 文件，并且这些子包之间是独立的，没有依赖关系，如果没有主包，则新定一个主包，并将路径定义增加到主包内； - - 如果多个子包中都包含 abi/api 文件，并且这些子包不是独立的，则需要找出这条依赖线中最底层的 rpm，比如 common 或者 libs，然后将路径定义增加到这个底层 rpm 中； -- 使用样例 - - 在 `%install` 阶段生成 abi/api 文件，注意需要将脚本调用放在最后 - ``` - %install - %make_install docdir=%{_pkgdocdir} - # remove unpackaged files from the buildroot - rm -f $RPM_BUILD_ROOT%{_libdir}/*.la - %generate_compatibility_deps - ``` - - 打包 abi/api 文件 - ``` - %files - %dir %{abidir} - %{_libdir}/libasound.so.* - %{abidir}/libasound.so.dump - %{_bindir}/aserver - %{abidir}/aserver-option.list - ``` - - 验证 abi/api 的有效性 - ``` - # rpm -qpl alsa-lib-1.2.7.2-2.an23.x86_64.rpm | grep dump - /usr/lib/compatibility/alsa-lib/libasound.so.dump - /usr/lib/compatibility/alsa-lib/aserver-option.list - ``` - - 验证 abi/api 的 provides - ``` - # rpm -qp alsa-lib-1.2.7.2-2.an23.x86_64.rpm --provides | grep abi - abi(alsa-lib) = 1.2.7.2 - - # rpm -qp alsa-lib-1.2.7.2-2.an23.x86_64.rpm --provides | grep api - api(alsa-lib) = 1.2.7.2 - ``` - - - -## 3 字段介绍和标准 - -| **spec header** | 增加 anolis_release 的定义，从 1 开始递增 | | -| --- | --- | --- | -| **字段** | **定义** | **是否可选** | -| Name | 包的基本名称，应与 SPEC 文件名匹配。 | 必选 | -| Epoch | 超级版本号。
1. 用于修正版本号，比如：0.20.0 版本 更改成 21.1
2. 初始化时， epoch 为 1，每次修正版本可以递增
3. 不可过度使用
4. 其他引用 %{version}-%{relase} 需要修改成：%{epoch}:%{version}-%{relase} |可选| -| Version | 软件的上游版本号。正式发布的 release/tag 版本号。 |必选| -| Release | 此版本软件的发布次数。
1. 初始值为： %{anolis_release}%{?dist}
2. 每次构建递增 anolis_release
3. 构建软件新version 时 anolis_release 需要重置为 1 |必选| -| Summary | 一个简短的、单行的软件包摘要。 |必选| -| License | 被打包的软件的许可证，所有许可证的并集。 |必选| -| URL | 该软件的上游项目网站。 |必选| -| Source0 | 上游源代码压缩存档的路径。这应该指向存档的可访问且可靠的存储，例如，上游页面而不是打包程序的本地存储。
如果需要，可以添加更多 SourceX 指令，每次递增编号，例如：Source1、Source2、Source3 等。 |必选| -| Patch0 | 对源码进行的修改以补丁的形式。
可以添加更多 PatchX 指令，每次递增编号，例如：Patch1、Patch2、Patch3 等。|可选| -| BuildArch | 声明该软件的构建体系结构。
1. koji 构建时默认为：x86_64 和 aarch64
2. 本地构建时会自动继承构建它的机器的体系结构
3. 如果不依赖体系结构，可以声明：BuildArch: noarch
4. 如果仅涉及一个架构，则需要将对应的架构声明：BuildArch：x86_64 或 BuildArch：aarch64 |可选| -| ExcludeArch | 声明该软件不需要的架构体系。
1. 默认不需要
2. 指定不进行编译的架构，举例：ExcludeArch: x86_64 | 可选 | -| ExclusiveArch | 声明该软件需要的架构体系。
1. 默认不需要
2. 指定进行编译的架构，举例：ExclusiveArch: x86_64 | 可选 | -| BuildRequires | 声明该软件构建所需要的全部软件包列表。
1. 有多个条目 BuildRequires 每个条目在 SPEC 文件中各占一行
2. 每个条目内不同软件使用空格隔开
3. 直接声明依赖软件的 package name，不要包含： %{_isa}、/usr/bin/xx、pkg-config(xx)、/usr/lib64/xx.so 等 |必选| -| Requires | 声明该软件运行所需要的全部软件包列表。
1. 有多个条目 Requires 每个条目在 SPEC 文件中各占一行
2. 每个条目内不同软件使用空格隔开
3. 直接声明依赖软件的 package name，不要包含： %{_isa}、/usr/bin/xx、pkg-config(xx)、/usr/lib64/xx.so 等
4. 需要声明依赖软件的版本限制时，如果是其他软件，则尽量使用 version，特殊情况增加 release；如果是本软件，则精确到 release；如果是 doc 包则使用 %{ERV} ，可以省略 epoch 的检查。 |必选| -| **spec body** | || -| **字段** | **定义** | **是否可选** | -| %description | RPM 中打包的软件的完整描述。该描述可以跨越多行并且可以分成段落。 | 必选 | -| %prep | 用于准备软件包构建所需要的源码。
1. 路径信息：将 tar.gz 从 ～/rpmbuild/SOURCES/ 目录下解压到 ～/rpmbuild/BUILD/ 下
2. 建议使用 %autosetup -n %{name}-%{version} -p1，可以自动按照补丁定义顺序将补丁以 -p1 形式打入
3. 允许在此处拷贝 source 文件，例如：cp %{SOURCE1} ./
4. 也允许去执行一些 shell 脚本 | 必选 | -| %build | 将软件包的源码进行编译阶段。
1. 路径信息：在 ～/rpmbuild/BUILD/%{name}-%{version}/ 下
2. 执行构建可以根据源码语言去选择构建方式
3. 在构建过程中是个 chroot 环境，不允许联网 download 等动作
4. 不允许随意修改 flags 等 | 必选 | -| %install | 将软件包编译生成的文件复制到安装目录，进行预安装动作，即模拟所有 package 安装后的环境。
1. 路径信息： ～/rpmbuild/BUILDROOT/%{name}-%{version}/
2. 复制时，文件从 ～/rpmbuild/BUILD/%{name}-%{version}/ 拷贝到 ～/rpmbuild/BUILDROOT/%{name}-%{version}/
3. 复制文件时，需要保留文件的时间戳，采用 cp -p 或 install -p
4. 操作允许直接将 SourceX 文件拷贝到安装目录允许再该阶段直接生成新文件 | 必选 | -| %check | 用于测试软件的命令或一系列命令。
这通常包括诸如单元测试之类的东西，阶段能开则开，如果不能开启，声明不能开启的原因。 | 可选 | -| %files | 定义每个 package 的文件列表，并生成对应的 .rpm。
1. 文件布局必须布局遵循 [**FHS**](https://yuque.antfin-inc.com/bobac/pm1qpi/xz4m02) ，个别情况额外声明
2. 正确设置文件权限：目录 0755，文件 0644 root root，除非出于安全考虑需要使用特定的用户或组
3. 所有安装在 ～/rpmbuild/BUILDROOT/%{name}-%{version}/ 下的文件必须全部有唯一归属
4. 不允许包含具有攻击性、歧义性、宗教性、色情性、受限制使用的文件等
5. %doc 后面可以直接跟 ～/rpmbuild/BUILD/%{name}-%{version}/ 下的说明类文档：README、ChangeLog等
6. %license 后面可以跟～/rpmbuild/BUILD/%{name}-%{version}/ 下的版权文件：copying、license 等 | 必选 | -| %changelog | Version不同或Release构建之间的包发生的更改的记录。
1. changlog 的格式正确，包括：日期、提交者个人信息、版本信息、描述信息等
2. Message 简洁易懂，清晰明确 | 必选 | - - -## 4 check list -下面给出 spec 的 check list，可以自行检查。 - -| **分类** | **要求程度** | **详细内容** | **自检结果** | -| --- | --- | --- | --- | -| 宏定义 | must | 使用宏变量代替硬编码的目录名称 | | -| | must | 不要出现其他 OS 发行版的宏，比如：fedora、rhel、openEuler、opensuse等 | | -| | should | spec 中的宏统一使用同一种格式 | | -| | should | 可以采用 %bcond_with 和 %bcond_without 来作为开关控制特性状态 | | -| | should | 宏定义时，%global 优先于 %define | | -| | should | 不使用 %if 0 作为判断条件 | | -| | should | 关于 python/perl/rust/golang/ruby/meson 等宏的使用，遵循各个 rpm-macros 包中的定义。 | | -| 基本信息 | must | spec 的第一行增加 anolis_release 的定义：%define anolis_release 1 | | -| | must | Name 和 package 命名匹配 | | -| | must | Epoch 用来修正版本号，但不得过度使用 | | -| | must | Version 为正式发布的 release/tag 版本，如果采用 rc 版本，则 version 需要定义为 xx~rc1，post 版本需要定义为：xx-post1 | | -| | must | Release 使用 %{anolis_release}%{?dist} | | -| | must | License 与实际的许可证相匹配，不存在缺失或者扩大 | | -| | should | 如果存在多个 license，建议给多个 license 加以注释 | | -| | must | Url 真实可用，属于上游源真实地址 | | -| | must | Source0 地址支持 curl 或者 wget 方式进行直接下载 | | -| | must | Source0 对应的源码包的 md5 值与开源社区的 md5 值相同 | | -| 依赖阶段 | must | Buildrequires 中声明所有的第一层构建依赖，且全部使用 package name 进行声明，并要求构建依赖以 rpm 形式存在相同 OS 版本构建源里，不允许其他方式引入 | | -| | must | Requires 中声明所有的第一层运行依赖，且全部使用 package name 进行声明，并要求运行依赖以 rpm 形式存在相同 OS 版本的 yum 源里，不允许其他方式引入 （禁止安装后执行 pip install 等动作） | | -| | must | 声明 devel 或其他子包对于主包或者 libs 的依赖时，需要增加版本限制: Requires: %{name} = %{epoch}:%{verison}-%{release} | | -| | should | 如果对依赖软件的版本有限制，则限制到软件包的 %{version} 即可，不需限制到 %{release} ，例：BuildRequires: glibc >= 2.32 || -| | should | 声明 buildrequires 和 requires 时，不要添加 %{?_isa} | | -| | should | 使用 provides 对外提供功能时，和以前版本保持一致，以前有加版本号，则需要一直加下去，如果以前没有加版本号，则不要增加 | | -| | should | 使用 obsoletes 时，需要增加对应版本号 | | -| 补丁文件 | must | 1. Patch 和 Souce 采用序号区分自研和开源三方
2. 自研补丁序号从100、1000、10000等编号开始 | | -| | should | Patch 序号连续，并保持一种规范 | | -| | should | 每个 patch 或 source 内有详细的修改原因和原链接地址 | | -| 架构阶段 | must | 至少在一种架构上构建成功，如果存在仅在部分架构上构建，可以使用 BuildArch（白名单）或者 ExcludeArch（黑名单） | | -| | must | Anolis OS 23 不支持 32 位，不支持multilib，请去除对其他架构的支持 | | -| | should | 合理使用 ifarch 和 ifnarch 的区别 | | -| 子包划分 | must | 有定义 doc 子包，且定义正确（依赖、架构） | | -| | must | python 类软件仅生成 python3 子包，不再支持 python2 | | -| 准备阶段 | should | 在 %prep 阶段采用 %autospec 进行自动解压并打补丁，保持 spec 简洁，如果存在与架构相关的补丁时，可以不采用 %autospec | | -| 构建阶段|must|在 %build 阶段不允许随意修改 flags，如果要修改，需要在 spec 中备注原因|| -| | must | 在 %build 阶段不允许随意禁用 PIE | | -| | should | 在 %build 阶段尽量采用多线程进行编译，提高构建速度 | | -| | should | 在 %build 和 %install 阶段使用宏变量要保持一致，比如：%{buildroot} 或者 $RPM_BUILD_ROOT | | -| 安装阶段 | must | 在 %install 阶段复制文件时，需要保留文件的时间戳，比如 cp -p 或者 install -p | | -| 脚本阶段| must | 如果存在动态库，则必须在 %post 和 %postun 阶段调用 %ldconfig | || -| | must | 如果存在 service 文件时，需要在 %post、%postun 和 %preun 中对服务作出对应动作（比如：%post %systemd_post xxx.service） | | -| 打包阶段 | must | %files 阶段文件系统布局遵循 FHS，个别特殊情况可以加以说明 | | -| | must | %files 阶段正确设置文件权限：目录 0755，文件 0644 root root，除非出于安全考虑需要使用特定的用户或组 | | -| | must | %files 里不允许有重复文件，一个文件仅能有一个归属 | | -| | must | %files 里不允许包含具有攻击性、歧义性、宗教性、色情性、受限制使用的文件等 | | -| | must | %doc 存放 readme、changelog、authors 等文件 | | -| | must | %license 存放 copying、license 等许可证文件 | | -| | must | 可以使用 %find_lang 宏来处理 locale 文件，进行自动打包相关文件。例：%find_lang %{name} | | -| | must | 如果存在需要保存配置的 conf 文件，需要声明 %config(noreplace) xxx.conf | | -| | must | 如果存在头文件，则需要放置在 devel 包内 | | -| | must | 如果有动态库，则包含后缀的库文件放在主包或者 libs 包，不包含后缀的库文件要放在 devel 中 | | -| | must | 如果有静态库，则静态库需要放置在 static 包内 | | -| | must | 公共的目录名称不可以通过 %dir 被重复定义，比如：%{_libdir}、%{_bindir} | | -| changlog 阶段 | must | changlog 的格式正确，包括：日期、提交者个人信息、版本信息、描述信息等 | | -| | should | changlog 的描述信息简洁易懂 | | - diff --git a/TECHNOLOGY_DOCS/GITEE/306-instruction-manual-of-rpmbuild.md b/TECHNOLOGY_DOCS/GITEE/306-instruction-manual-of-rpmbuild.md deleted file mode 100644 index 4fd365691f4f0ddecd22d4f0de774c2aaa084781..0000000000000000000000000000000000000000 --- a/TECHNOLOGY_DOCS/GITEE/306-instruction-manual-of-rpmbuild.md +++ /dev/null @@ -1,1235 +0,0 @@ -# 306 rpmbuild 构建指导手册 -该文章介绍了 spec 编写和构建过程中的细节和技术原理，相当于指导手册。 -## 1 宏介绍 -在软件包构建的过程中，为了防止过多使用硬编码路径和常用路径引用问题，增加了“宏”的概念。将一些常用路径或者变量值通过宏变量定义出来，并可以在整个 Anolis OS 发行版中使用。 -spec 宏目前来源于三种：系统宏、各种编程语言的宏和自定义宏 -### 1.1 系统宏 -当前社区里已经提供了一些系统宏文件，用于在软件包编译过程中使用，包括：系统路径、系统文件、编译选项、编译方式等，下面以 Anolis OS 23 的环境举例。 -目前由 rpm 软件对外提供了 spec 定义和编译过程中的宏 ：`/usr/lib/rpm/macros`： - -``` -// 宏文件路径 -[root@localhost ~]$ ls -l /usr/lib/rpm/macros --rw-r--r--. 1 root root 42715 3月 23 11:05 /usr/lib/rpm/macros - -// 查询宏文件所属的 rpm -[root@localhost ~]$ rpm -qf /usr/lib/rpm/macros -rpm-4.17.0-4.an23.x86_64 - -// 查看宏文件里定义的宏 -[root@localhost ~]$ cat /usr/lib/rpm/macros -%_sourcedir %{_topdir}/SOURCES -%buildroot %{_buildrootdir}/%{NAME}-%{VERSION}-%{RELEASE}.%{_arch} -%_prefix /usr -%_exec_prefix %{_prefix} -%_bindir %{_exec_prefix}/bin -%_sbindir %{_exec_prefix}/sbin -%_libexecdir %{_exec_prefix}/libexec -%_datadir %{_prefix}/share -%_sysconfdir /etc -%_sharedstatedir %{_prefix}/com -%_localstatedir %{_prefix}/var -%_lib lib -%_libdir %{_exec_prefix}/%{_lib} -%_includedir %{_prefix}/include -%_infodir %{_datadir}/info -%_mandir %{_datadir}/man -....... -``` - -编译选项相关的基础宏： -``` -// 宏文件路径 -[root@localhost ~]$ ls -l /usr/lib/rpm/anolis/macros --rw-r--r-- 1 root root 16707 Mar 16 05:14 /usr/lib/rpm/anolis/macros - -// 查询宏文件所属的 rpm -[root@localhost ~]$ rpm -qf /usr/lib/rpm/anolis/macros -system-rpm-config-23-4.an23.noarch - -// 查看宏文件里定义的宏 -[root@localhost ~]$ cat /usr/lib/rpm/anolis/macros - GCC toolchain -%__cc_gcc gcc -%__cxx_gcc g++ -%__cpp_gcc gcc -E - -# Clang toolchain -%__cc_clang clang -%__cxx_clang clang++ -%__cpp_clang clang-cpp -....... -``` - -### 1.2 各种编程语言宏 -社区里除了系统软件，对外还提供了很多编程语言的软件，包括不限于：python、perl、go、rust、java 等。 -``` -// 查询 yum 源里提供的 macros rpm -[root@localhost root]$ yum list | grep macros | grep an23 -cmake-rpm-macros.noarch 3.22.3-1.an23 @BaseOS -efi-srpm-macros.noarch 5-1.an23 @BaseOS -go-srpm-macros.noarch 3.0.15-1.an23 @BaseOS -perl-srpm-macros.noarch 23-1.an23 @BaseOS -pyproject-rpm-macros.noarch 1.0.0-1.an23 @BaseOS -python-rpm-macros.noarch 3.10-23.1.an23 @BaseOS -python-srpm-macros.noarch 3.10-23.1.an23 @BaseOS -python3-rpm-macros.noarch 3.10-23.1.an23 @BaseOS -rust-srpm-macros.noarch 23-1.an23 @BaseOS -systemd-rpm-macros.noarch 250.4-1.an23 @BaseOS -fonts-rpm-macros.noarch 1:4.0.2-1.an23 BaseOS -fonts-rpm-macros.noarch 1:4.0.2-1.an23 koji -fonts-srpm-macros.noarch 1:4.0.2-1.an23 BaseOS -fonts-srpm-macros.noarch 1:4.0.2-1.an23 koji -go-rpm-macros.x86_64 3.0.15-1.an23 AppStream -go-rpm-macros.x86_64 3.0.15-1.an23 koji -perl-macros.noarch 4:5.34.0-6.an23 BaseOS -perl-macros.noarch 4:5.34.0-6.an23 koji -python-qt5-rpm-macros.noarch 5.15.6-1.an23 koji -qt5-rpm-macros.noarch 5.15.5-1.an23 koji -qt5-srpm-macros.noarch 5.15.5-1.an23 koji -texlive-bbm-macros.noarch 9:svn17224.0-1.an23 koji -texlive-bbm-macros-doc.noarch 9:svn17224.0-1.an23 koji -texlive-chemmacros.noarch 9:svn56983-1.an23 koji -texlive-chemmacros-doc.noarch 9:svn56983-1.an23 koji -texlive-circuit-macros.noarch 9:svn57308-1.an23 koji -texlive-ling-macros.noarch 9:svn42268-1.an23 koji -texlive-macros2e-doc.noarch 9:svn46026-1.an23 koji -texlive-macroswap.noarch 9:svn31498.1.1-1.an23 koji -texlive-macroswap-doc.noarch 9:svn31498.1.1-1.an23 koji -``` - -### 1.3 自定义宏 -允许在 spec 的头部自定义宏变量，通过 `**%global 宏变量名称 宏变量值** `格式定义宏，在下文通过 `**%{宏变量名称}**`引用，样例： - -``` -// % %global 宏变量名称 宏变量值 -%global pname ruamel-yaml - -// 使用宏变量 -Name: python-%{pname} - -// 拓展： -spec 中允许对基本信息字段进行宏拓展使用，比如上述第 5 行的 Name 字段，可以采用 %{name} 进行引用 -``` - -### 1.4 查询已有宏 - -- 通过 `rpm -E %{xxx}`来查询 xxx 宏的实际内容 - ``` - # 查询 %{_bindir} 的值 - [root@localhost ~]$ rpm -E %{_bindir} - /usr/bin - ``` - -- %bcond_with 和 %bcond_without 介绍 - - 通常在开启或者关闭某个特性时，可以使用这两个变量。使用方式为： - ``` - // 定义 - %bcond_without testsuite - - // 使用 - %check - %if %{with testsuite} - ..... - %endif - ``` - - - %bcond_without xx ：是指不需要去除 xx 特性，即等价于开启 xx 特性，在定义该宏之后，会在内部自动生成一个全局变量 with_xx ，并对 with_xx 进行赋值 1，即 with_xx =1。这样在使用该变量时，通过with 方法读取 with_xx 变量的值，从而生成判断结果。 - - %bcond_with xx：即关闭 xx 特性，其生成的全局变量 with_xx = 0，从而 with 的判断为假。 - -## 2 rpmbuild 详解 -### 2.1 代码准备 -在准备将某款软件进行构建时，需要准备的文件至少为：spec + source.tar.gz，spec文件用于指导生成rpm，source.tar.gz 为源码，有时额外还会存在一些其他 source 文件或者 patch 文件。 -下面以 lld 软件作为样例讲解： -``` -[root@localhost ~]$ ll ～/rpmbuild/SOURCES/ -total 1492 --rw-r--r-- 1 root root 1900 Aug 4 02:10 0001-PATCH-lld-CMake-Check-for-gtest-headers-even-if-lit..patch --rw-r--r-- 1 root root 20288 Aug 4 02:10 0002-PATCH-lld-Import-compact_unwind_encoding.h-from-libu.patch --rw-r--r-- 1 root root 699 Aug 4 02:10 lit.lld-test.cfg.py --rw-r--r-- 1 root root 1473868 Aug 4 02:10 lld-13.0.1.src.tar.xz --rw-r--r-- 1 root root 566 Aug 4 02:10 lld-13.0.1.src.tar.xz.sig --rw-r--r-- 1 root root 6129 Aug 4 02:10 lld.spec --rw-r--r-- 1 root root 488 Aug 4 02:10 README.md --rw-r--r-- 1 root root 1362 Aug 4 02:10 run-lit-tests --rw-r--r-- 1 root root 2222 Aug 4 02:10 tstellar-gpg-key.asc -``` -### 2.2 %prep 解压 -#### 2.2.1 文件准备 -%prep 阶段的作用就是准备构建所需要的文件，这里一般包括： - - 解压 source.tag.gz - - 打补丁动作 - - 拷贝 source 文件、或者脚本等 -#### 2.2.2 解压方式 -解压是针对 Souce0 定义的 source.tar.gz 进行解压，解压有两种方式：%setup 和 %autosetup，这两种方式的详细介绍如下，可以根据自己软件需要进行选择使用： - - - `%setup -q -n %{name}-%{version}` - - -q ：代表采用安静模式进行解压 - - -n ：声明解压之后的源码目录名称，一般为 %{name}-%{version}，但是可以手动对 source.tag.gz 进行解压后查看具体目录名称 - - 当存在补丁时，需要将每个补丁进行声明打入，并可以针对不同的补丁指定不同的忽略目录，且可以自己指定补丁打入的顺序 - - 在存在与架构相关的补丁时，比较方便，指定对应的架构才将补丁打入用 - - ``` - ...... - Patch0: xxxxxx.patch // 一层路径 - Patch1: xxxxxx.patch // 两层路径 - Patch2: xxxxxx.patch // 一层路径 - Patch3: xxxxxx.patch // 零层路径 - Patch4: x86_64-xxx.patch // 仅 x86_64 架构打入，一层路径 - ...... - - %prep - %setup -q -n %{name}-%{version} - %patch0 -p1 - %patch1 -p2 - %patch3 -p0 - %patch2 -p1 - %ifarch x86_64 - %patch4 -p1 - %endif - ``` - - - `%autosetup -n %{name}-%{version} -p1` - - -n : 同上 - - -p1：按照 spec 内 Patch 的定义顺序全部打入，并且全部采用 -p1 忽略一层目录的结构打入补丁。 - - 当存在与架构相关的补丁时，不再使用 - - 代码举例： - - ``` - ..... - Patch0: xxxxxx.patch // 一层路径 - Patch1: xxxxxx.patch // 一层路径 - ...... - - %prep - %autosetup -q -n %{name}-%{version} -p1 - ``` - - - 此处也可以执行其他动作，比如解压其他 source.tar.gz 、拷贝其他 source 文件等 - - ``` - %prep - %autosetup -q -n %{name}-%{version} -p1 - tar -xvf %{SOURCE1} ./ - ``` - -#### 2.2.3 路径信息 - -- 本地编译时，源码一般存放在 `~/rpmbuild/SOURCES/`下， spec 文件在 `~/rpmbuild/SOURCES/` 或者 `~/rpmbuild/SPECS/`下都可，但是 koji 编译时，spec 文件在`~/rpmbuild/SPECS/`下 -- 在执行完 %prep 后，源码将被解压到 `~/rpmbuild/BUILD` 下 -- 通常可以使用 `rpmbuild -bp ~/rpmbuild/SOURCES/xxx.spec --nodeps`来查看解压结果，并且可以在日志中看到 patch 是有被打入的。 - - ``` - [root@localhost ~]$ rpmbuild -bp ~/rpmbuild/SOURCES/lld.spec --nodeps - Executing(%prep): /bin/sh -e /var/tmp/rpm-tmp.cJtqDn - + umask 022 - + cd /root/rpmbuild/BUILD - + /usr/lib/rpm/redhat/gpgverify --keyring=/root/rpmbuild/SOURCES/tstellar-gpg-key.asc --signature=/root/rpmbuild/SOURCES/lld-13.0.1.src.tar.xz.sig --data=/root/rpmbuild/SOURCES/lld-13.0.1.src.tar.xz - gpgv: Signature made Wed Feb 2 09:58:19 2022 EST - gpgv: using RSA key 474E22316ABF4785A88C6E8EA2C794A986419D8A - gpgv: Good signature from "Tom Stellard " - + cd /root/rpmbuild/BUILD - + rm -rf lld-13.0.1.src - + /usr/bin/xz -dc /root/rpmbuild/SOURCES/lld-13.0.1.src.tar.xz - + /usr/bin/tar -xof - - + STATUS=0 - + '[' 0 -ne 0 ']' - + cd lld-13.0.1.src - + /usr/bin/chmod -Rf a+rX,u+w,g-w,o-w . - + /usr/bin/cat /root/rpmbuild/SOURCES/0001-PATCH-lld-CMake-Check-for-gtest-headers-even-if-lit..patch - + /usr/bin/patch -p2 -s --fuzz=0 --no-backup-if-mismatch - + /usr/bin/cat /root/rpmbuild/SOURCES/0002-PATCH-lld-Import-compact_unwind_encoding.h-from-libu.patch - + /usr/bin/patch -p2 -s --fuzz=0 --no-backup-if-mismatch - + exit 0 - [root@localhost SOURCES]$ ll ~/rpmbuild/BUILD/ - total 8 - drwxr-xr-x 16 root root 4096 Aug 4 02:44 lld-13.0.1.src - ``` - -### 2.3 %build 构建 -#### 2.3.1 编译器 -软件包使用的编译器由软件源码的语言来决定，现在比较流行的编译器种类比较多：gcc、clang 等。但是，软件包应该默认使用 gcc 作为编译器（对于 gcc 支持的所有语言），如果上游不支持使用 gcc 构建，则应该使用clang。 -但是，如果有很好的技术原因，打包者可以选择不使用默认编译器。不使用默认编译器的有效技术原因示例包括但不限于： - -- 默认编译器无法正确构建包。 -- 打包者需要禁用编译器功能（例如 LTO），以便默认编译器正确编译他们的包。 -- 默认编译器需要更长的时间来构建包。 -- 默认编译器缺少一个对包有利于的特性。 -- 选择使用非默认编译器的打包人员应在spec文件的注释中记录做出这一决定的原因。 - -#### 2.3.2 编译 Flags - -用于构建包的编译器必须遵守系统 rpm 默认配置中设置的编译器 Flags。 -对于 C、C++ 和 Fortran 代码, %optflags 宏包含这些 flags。不鼓励为了性能优化而覆盖这些 flags（例如，-O3 代替 -O2）。如果可以提供 benchmark 结果，显示这段代码有明显的性能优化，那可以根据具体情况重新审视。如果有充分的理由，可以添加、重写或过滤这些flags；这样做的理由必须记录在 spec 文件中。 -通常允许使用某些与安全相关的flags，这些flags可能会略微降低性能，但是相对某些程序增加的安全性收益来说是值得的。 -默认情况下，启用PIE，如果要在spec中禁用，可以通过： -``` -%undefine _hardened_build -``` -但是以下场景不允许禁用PIE： - -- 软件包长期运行，意味着它很可能会启动并继续运行，直到机器重新启动，而不是按需启动，并在空闲时退出。 -- 软件包具有 suid 二进制文件或具有功能的二进制文件。 -- 软件包以 root 身份运行。 - -#### 2.3.3 并行构建 - -在编译过程中，可以指定多线程来加快构建速度。一般是在 make 后增加 -jxx，来表示用 xx 线程编译，同时可以直接使用 `%make_build` 进行编译，默认增加多线程。 -``` -[root@localhost SOURCES]$ rpm -E %{make_build} -/usr/bin/make -j96 -``` -其他语言也都有对应的编译方式，比如 %cmake_build，%meson_build、%cargo_build 等，这些宏都自带了多线程。 - -``` -[root@localhost ~]$ rpm -E %{cmake_build} -/usr/bin/cmake --build "anolis-linux-build" -j96 --verbose - -[root@localhost ~]$ rpm -E %{cargo_build} -/usr/bin/env CARGO_HOME=.cargo RUSTC_BOOTSTRAP=1 RUSTFLAGS='-Copt-level=3 -Cdebuginfo=2 -Ccodegen-units=1 -Clink-arg=-Wl,-z,relro -Clink-arg=-Wl,-z,now --cap-lints=warn' /usr/bin/cargo build -j96 -Z avoid-dev-deps --release -``` - -#### 2.3.4 构建目录 -在构建阶段，所有的构建动作都在路径：`～/rpmbuild/BUILD/%{name}-%{version}/`下，并且编译生成的文件也只允许生成在当前目录下，不允许对构建环境的系统目录进行操作，比如：`/tmp`、` /home`。 - -#### 2.3.5 网络访问 -构建系统中的软件包是在一个模拟的 chroot 中构建的，无法访问互联网。包不能依赖或使用不是它们自己创建的任何网络资源。 - -### 2.4 %install 预安装 -在完成构建后，需要对构建结果进行一个安装，这里准备了一个预安装的环境，用于模拟安装环境。 - -#### 2.4.1 安装路径 -预安装的绝对路径为：`～/rpmbuild/BUILDROOT/%{name}-%{version}/`，一般可以使用 `%{buildroot} `进行引用。 - -#### 2.4.2 怎么安装 -一般该阶段执行的动作都是将文件从**构建目录**拷贝到**安装目录**，举例： -``` -install: - @echo "BEGIN INSTALL xxx" - mkdir -p $(BINDIR) - -install -m 0755 $(PKGPATH)/xxx $(BINDIR) -``` -#### 2.4.3 其他动作汇总 -``` -%install -%make_install - -// 创建路径 -mkdir -p %{buildroot}/%{_datadir}/%{name} - -// 复制 source 文件到安装目录 -install -p -m 0644 %{SOURCE1} %{buildroot}/%{_datadir}/%{name}/ - -// 新生成文件到安装目录 -pushd %{buildroot}/%{_datadir}/%{name}/ -touch xxx -popd - -// 删除多余文件 -rm -f %{buildroot}/%{_libdir}/%{name}/*.{a,la,so} -``` - -### 2.5 %files 打包 - -spec 中通过 %files 来规定 package 包含哪些文件，对于 %install 里的文件要求如下： - - - 每个文件只能有一个归属，不可以同时属于两个 package - - 所有在 %install 阶段安装到 %{buildroot} 下的文件，必须全部都有归属 - - 当然如果想忽略某个 %{buildroot} 下的文件，可以使用 %exclude 进行去除，但不推荐这种方式，建议直接在 %install 阶段里删除对应文件 - - 不允许声明不在 %{buildroot} 下的文件 - -#### 2.5.1 文件系统布局 -文件系统层次结构标准（FHS)，定义了 Linux 操作系统中的主要目录及目录内容。[FHS](https://refspecs.linuxfoundation.org/fhs.shtml ) 由 Linux 基金会维护。主要介绍了每个结构的含义和应该存放的文件。 - -| / | 第一层次结构的根，整个文件系统层次结构的根目录 | -| --- | --- | -| /bin | 需要在单用户模式可用的必要命令（可执行文件）；面向所有用户，例如：cat、ls、cp | -| /sbin | 必要的系统二进制文件，面向管理员用户。例如：init、ip、mount | -| /boot | 引导程序文件，系统引导文件，如内核 vmlinuz、ramfs 文件，initrd，以及 grub（bootloader）；通常划分单独的分区 | -| /dev | 必要设备, 例如：/dev/null，/dev/sda | -| /etc | 系统范围内的配置文件 | -| /home | 用户的家目录，包含保存的文件、个人设置等
每一个用户的家目录通常默认为 /home/$USER | -| /lib | /bin/ 和 /sbin/中二进制文件必要的库文件。 | -| /lib64 | /bin/ 和 /sbin/中二进制文件必要的库文件（64位）。 | -| /lost+found | 系统断电时候临时保存的，默认为空 | -| /media | 可移除媒体(如CD-ROM)的挂载点 | -| /mnt | 临时挂载的文件系统 | -| /opt | 备用目录，第三方程序的安装目录，默认为空 | -| /proc | 虚拟文件系统，将内核与进程状态归档为文本文件。例如：uptime、 network。在 Linux 中，对应 Procfs 格式挂载。
/proc/meminfo：查看内存信息
/proc/cpuinfo：cpu信息
/proc/mounts：挂载信息
/proc/loadavg：负载信息
/proc/partitions：磁盘信息 |
-| /root | 超级用户的家目录 | -| /selinux | selinux 相关的安全策略等信息存储的位置，默认为空 | -| /srv | 为服务提供数据存放位置，默认为空 | -| /sys | 虚拟文件系统，用于输出当前系统上硬件设备相关信息的虚拟文件系统 | -| /tmp | 临时文件(参见 /var/tmp)，在系统重启时目录中文件不会被保留。 | -| /usr | 用于存储只读用户数据的第二层次； 包含绝大多数的(多)用户工具和应用程序。 | -| /var | 频繁发生变化的文件——在正常运行的系统中其内容不断变化的文件，如日志，脱机文件和临时电子邮件文件。
/var/cache：应用程序缓存数据目录
/var/lib：应用程序状态信息数据
/var/local：专用于/usr/local下的应用程序存储可变数据
/var/log：日志目录文件
/var/log/messages系统日志
/var/log/secure 安全日志 SSH连接日志
/var/lock：锁文件
/var/run：与运行中进程相关的数据；通常存放进程的PID文件
/var/spool：应用程序数据池
/var/tmp：保存系统两次重启之间产生的临时数据 | - -但是也存在一些例外： - -- 不允许在/或者/usr下创建目录 -- FHS 没有定义 libexecdir，rpm 的宏中包含了 %{_libexecdir} 的定义，Libexecdir（也就是系统上的 /usr/libexec）只应该用作可执行程序的目录，这些可执行程序是由其他程序运行的而不是由用户运行的。 -- /run 目录是 tmpfs，系统服务应该存放在该目录，/var/run 是 /run 的软链接。 -- /srv、/usr/local、/home/$USER 目录下禁止存放文件或目录 -- 有限使用 /opt，/etc/opt，/var/opt，如果想要安装文件到上述目录，最好是创建子目录，比如 /opt/anolis/。 -- Anolis OS 23 系统中将 / 下的几个目录与 /usr 下的几个目录合并 - - ``` - /bin - /usr/bin %{_bindir} - /sbin - /usr/sbin %{_sbindir} - /lib64 or /lib - /usr/lib64 or /usr/lib %{_libdir} - /lib - /usr/lib %{_prefix}/lib - ``` - -- 举例：用户发现 /bin/sh 与 /usr/bin/sh 是同一个文件，如果一个rpm指定 - - ``` - %files - /bin/sh - ``` - 可以满足 /bin/sh 的文件依赖，但是无法满足 /usr/bin/sh 的文件依赖。所以 %files 中需要列出历史记录中放置在 /bin，/sbin，/lib 或者 /lib64 的内容；历史记录中放在 /usr/bin，/usr/sbin 目录下的内容以 %{_bindir}、%{_sbindir} 在 %files 中列出。如果对于程序放在哪个目录不清楚，可以通过虚拟的 provides 来列出备用路径，如： - ``` - ....... - Provides: %{_sbindir}/ifconfig - ....... - - %files - /sbin/ifconfig - ``` - -#### 2.5.2 rpath注意事项 - -- 不允许使用 rpath。 - - rpath 是在链接二进制文件时使用硬编码指定特定的库路径（使用 -rpath 或 -R 标志）。动态链接器和加载器 (ld.so) 会解析可执行文件对共享库的依赖关系并加载所需的内容。但是，当使用 -rpath 或 -R 时，位置信息会被硬编码到二进制文件中，并在执行开始时由 ld.so 检查。由于 Linux 动态链接器通常比硬编码路径更智能，因此我们通常不允许使用 rpath。 - rpmdevtools 软件包中包含一个名为 check-rpaths 的工具，并且在 ~/.rpmmacros 中配置 `%__arch_install_post` 宏： - - ``` - %__arch_install_post \ - /usr/lib/rpm/check-rpaths \ - /usr/lib/rpm/check-buildroot - ``` - - 运行 check-rpaths 后，可以得到错误提示： - - ``` - ERROR 0001: file '/usr/bin/xapian-tcpsrv' contains a standard rpath '/usr/lib64' in [/usr/lib64] - ``` - - 必须删除由 check-rpaths 标记的任何 rpath。 - -- 允许内部库文件使用 rpath - - 有些程序在安装内部库时，通常不会安装在系目录，这些内部库仅被包内程序使用，并不会给外部程序使用，这种情况戏下，可以使用 rpath 来查找这些库。 - ``` - # Internal libraries for myapp are present in: - %{_libdir}/myapp/ - %{_libdir}/myapp/libmyapp.so.0.3.4 - %{_libdir}/myapp/libmyapp.so - - # myapp has an rpath to %{_libdir}/myapp/ - readelf -d /usr/bin/myapp | grep RPATH - 0x0000000f (RPATH) Library rpath: [/usr/lib/myapp] - ``` - -- rpath 替代方案 - - 通常，使用 rpath 是因为二进制文件在非标准位置（标准位置是/lib、/usr/lib、/lib64、/usr/lib64）寻找库。如果需要将库存储在非标准位置（例如 /usr/lib/foo/），则应该在 /etc/ld.so.conf.d/ 中包含一个自定义配置文件。 - 例如，如果我将 libfoo 库放在 /usr/lib/foo 中，我就需要在 /etc/ld.so.conf.d/ 中创建一个名为“foo.conf”的文件，文件内容为 '/usr/lib/foo' 。 - ``` - %install - ...... - mkdir -p ${RPM_BUILD_ROOT}%{_sysconfdir}/ld.so.conf.d - echo "%{_libdir}/foo" > %{buildroot}%{_sysconfdir}/ld.so.conf.d/%{name}.conf - ...... - ``` - - - 删除 rpath: - - 如果应用程序包含 configure，configure添加--disable-rpath - - 如果应用程序使用 libtool，请将以下几行添加到 %configure 之后的spec中 - - ``` - %configure - sed -i 's|^hardcode_libdir_flag_spec=.*|hardcode_libdir_flag_spec=""|g' libtool - sed -i 's|^runpath_var=LD_RUN_PATH|runpath_var=DIE_RPATH_DIE|g' libtool - ``` - - - 直接修改代码或者Makefile来删除 -rpath 或者-R - - 作为最后的手段，有一个名为 chrpath 的包。安装此软件包后，对包含 rpath 的文件运行 chrpath --delete。需要在 spec 中增加 `BuildRequires: chrpath` 后，运行： - - ``` - chrpath --delete $RPM_BUILD_ROOT%{_bindir}/xapian-tcpsrv - ``` - -#### 2.5.3 权限和属主 -所有的目录和文件必须设置正确的权限。 - -- 每个文件都应该归 root:root 所有，除非出于安全考虑需要更具体的用户或组。 -- 目录默认权限为 0755 ，文件默认权限为 0644 ，除非有特定需求 -- 所有文件必须可读 -- 文件权限方式有几种方式： - - 在 %install 阶段，通过 chmod 和 chown 等命令修改权限 - - **在 %install 阶段执行拷贝命令时进行赋权限：**`install -m 0644 xxxx`， 建议使用该方式。 - - 在 %files 阶段统一增加 `%defattr(-,root,root)`，统一赋权限，但该项仅对没有默认值的文件生效 - - 在 %files 阶段对单个路径或者配置文件增加权限操作：`%dir %attr(0700, root, root) xxxx` - -#### 2.5.4 文件详情 -##### 2.5.4.1 license 许可证 -因为每款开源软件都是来源于上游社区，并且都含有自己的许可证。所以需要将许可证信息打入 rpm 包中。 -一般存在的形式为：COPYING 、License 等，解压开源码包即可查找到。 -``` -[root@localhost lld-13.0.1.src]$ ll -total 88 -drwxr-xr-x 3 root root 4096 Jan 20 2022 cmake --rw-r--r-- 1 root root 7232 Aug 4 02:44 CMakeLists.txt --rw-r--r-- 1 root root 879 Jan 20 2022 CODE_OWNERS.TXT -drwxr-xr-x 2 root root 4096 Jan 20 2022 COFF -drwxr-xr-x 2 root root 4096 Jan 20 2022 Common -drwxr-xr-x 6 root root 4096 Jan 20 2022 docs -> 这里也别忘记查看一下 -drwxr-xr-x 3 root root 4096 Jan 20 2022 ELF -drwxr-xr-x 4 root root 4096 Aug 4 02:44 include -drwxr-xr-x 5 root root 4096 Jan 20 2022 lib --rw-r--r-- 1 root root 15138 Jan 20 2022 LICENSE.TXT -> 看这里 -drwxr-xr-x 3 root root 4096 Jan 20 2022 MachO -drwxr-xr-x 2 root root 4096 Jan 20 2022 MinGW --rw-r--r-- 1 root root 678 Jan 20 2022 README.md -drwxr-xr-x 10 root root 4096 Jan 20 2022 test -drwxr-xr-x 3 root root 4096 Jan 20 2022 tools -drwxr-xr-x 4 root root 4096 Jan 20 2022 unittests -drwxr-xr-x 2 root root 4096 Jan 20 2022 utils -drwxr-xr-x 2 root root 4096 Jan 20 2022 wasm -``` - -在找到这个文件之后，可以直接使用 %license 的宏将文件从**源码包**目录直接打包至**rpm**包内，不需要再单独执行从编译目录拷贝到安装目录的动作。 - -``` -// 使用样例： -%files -%license LICENSE.TXT -``` - -##### 2.5.4.2 配置文件 - -- %config 标志 - - 配置文件在打包时，可以使用 %config 对配置文件进行标记，%config 额外还提供 %config(noreplace) 的形式，这样可以在软件包升级时不覆盖本地修改。当然是否选择 noreplace，还要根据具体软件包特点来定，推荐使用 %config(noreplace) 。 - 但 %config 仅能标记配置文件，其他文件不允许。 - - ``` - %files - %config /etc/%{package_name}/%{package_name}.conf - %config(noreplace) /etc/%{package_name}/%{package_name}-noreplace.conf - ``` - -- 配置文件的目录 - - 配置文件建议放到 /etc 下，不允许放在 /usr 下。 - -##### 2.5.4.3 systemd units - -systemd units文件的软件包必须将它们放入 %{_unitdir} 或 %{_userunitdir}。 -大多数 systemd 服务应该使用 %{_unitdir}，但是如果服务作为用户运行的话可以使用 %{_userunitdir}。如果想要使用这两个宏，则必须增加其对应的 rpm。 - -``` -[root@localhost ~]$ rpm -E %{_unitdir} -/usr/lib/systemd/system - -[root@localhost ~]$ rpm -E %{_userunitdir} -/usr/lib/systemd/user - -// 查询哪个 rpm 对外提供系统服务路径 -[root@localhost ~]$ cd /usr/lib/rpm -[root@localhost rpm]$ grep -nr '_unitdir' -macros.d/macros.systemd:9:%_unitdir /usr/lib/systemd/system -[root@localhost rpm]$ rpm -qf macros.d/macros.systemd -systemd-rpm-macros-250.4-1.an23.noarch -``` - -每个 service 文件都会有 scripts 伴随，一般用于设定服务启动时间、执行服务准备脚本等。主要分布在 %post -、%preun、%postun 阶段。 - -- 系统服务相关脚本 - - ``` - BuildRequires: systemd-rpm-macros - - [...] - %post - %systemd_post apache-httpd.service - - %preun - %systemd_preun apache-httpd.service - - %postun - %systemd_postun_with_restart apache-httpd.service - ``` - - 某些服务不支持重启（例如 D-Bus 和各种存储守护进程）。 如果升级时不应重新启动您的服务，请使用以下 %postun 脚本代替上述脚本： - - ``` - %postun - %systemd_postun apache-httpd.service - ``` - -- 用户服务相关脚本 - - 安装在 %_userunitdir 下的服务也是需要有对应的脚本设置启动或禁用。 - - ``` - BuildRequires: systemd-rpm-macros - - [...] - %post - %systemd_user_post %{name}.service - - %preun - %systemd_user_preun %{name}.service - ``` - -##### 2.5.4.4 命令行 - -命令行一般都被包含在主包内，存放路径为：%_bindir 或 %_sbindir，存在部分命令行直接放在 /bin 和 /sbin 下下，/bin 和 /sbin 是作为超链接存在。命令行对外是个可执行的二进制文件，用户根据自己的需求，设置对应的 option，并获取执行结果。 -``` -[root@localhost rpm]$ rpm -E %{_bindir} -/usr/bin - -[root@localhost rpm]$ rpm -E %{_sbindir} -/usr/sbin - -[root@localhost rpm]$ ll /bin -lrwxrwxrwx. 1 root root 7 Jun 16 2021 /bin -> usr/bin - -[root@localhost rpm]$ ll /sbin -lrwxrwxrwx. 1 root root 8 Jun 16 2021 /sbin -> usr/sbin -``` - -##### 2.5.4.5 动态库 - -动态库又叫共享库，一般存放在 %{_libdir} 下。如果为 64 位系统，%_libdir 为 /usr/lib64，如果为 32 位系统，_libdir 为 /usr/lib。但是也存在一些 so 文件，直接放在 /usr/lib 下，没有64 位 和 32 位的区分。 -注意：%files 声明 %{_libdir} 下的动态库时，尽量不要使用 * 的统配方式隐藏文件名，比如：libxx.so*。 -一般动态库有三种形态，需要严格按照划分方式规定每个 so 的归属。 - -``` -libxxx.so // 放在 devel 包，开发包，作为超链接直接对外提供，链接到 libxxx.so.1.1 -libxxx.so.1 // 放在主包或者 libs 包，作为超链接直接对外提供，链接到 libxxx.so.1.1 -libxxx.so.1.1 // 放在主包或者 libs 包，实际掉用的 so，当发生版本变更时，不影响对外提供 -``` - -举例： - -``` -[root@localhost rpm]$ ll /usr/lib64 | grep libffi -lrwxrwxrwx. 1 root root 15 3月 14 11:19 libffi.so -> libffi.so.8.1.0 -lrwxrwxrwx. 1 root root 15 3月 14 11:19 libffi.so.8 -> libffi.so.8.1.0 --rwxr-xr-x. 1 root root 45280 3月 14 11:19 libffi.so.8.1.0 - -[root@localhost rpm]$ rpm -qf /usr/lib64/libffi.so.8 -libffi-3.4.2-1.an23.x86_64 -[root@localhost rpm]$ rpm -qf /usr/lib64/libffi.so.8.1.0 -libffi-3.4.2-1.an23.x86_64 -[root@localhost rpm]$ rpm -qf /usr/lib64/libffi.so -libffi-devel-3.4.2-1.an23.x86_64 -``` - -##### 2.5.4.6 静态库 - -静态库是指 .a 或者 .la 的文件，存放路径也在 %{_libdir} 下。但是，我们的软件应该尽可能排除掉静态库，即静态库默认不对外提供。 -如果想要对外提供静态库，则可以生成 package-static 包，其他依赖静态库的可以在 spec 中增加对 package-static 的构建依赖。 -``` -[root@localhost ~]$ rpm -ql zlib-static -/usr/lib64/libz.a -/usr/share/licenses/zlib-static -/usr/share/licenses/zlib-static/README - -[root@localhost ~]$ ll /usr/lib64/libz.a --rw-r--r--. 1 root root 383514 3月 15 19:47 /usr/lib64/libz.a -``` - -##### 2.5.4.7 网络应用程序 - -一般 Web 应用程序应该将它们的内容放入 `%{_datadir}/%{name}`（即： /usr/share/%{name} ）中，而不是放在 /var/www/ 下，原因如下： - -- /var 应该包含可变数据文件和日志。 /usr/share 更适合这种情况。 -- 许多用户有可能已经在 /var/www 中拥有内容，我们不希望任何软件包覆盖用户信息。 -- FHS没有定义 /var/www - -##### 2.5.4.8 Tmpfiles.d - -tmpfiles.d 是用于管理守护进程的临时文件和运行时目录的服务，一般对应的路径为：/run 和 /run/lock。由于 /run 是一个 tmpfs 文件系统，因此每次重新启动时都必须重新创建它及其内容。 通常需要提前创建目录，最好使用 tmpfiles.d 机制来完成。 - -- tmpfiles.d 机制，对应路径为： %{_tmpfilesdir} -- 在 %{_tmpfilesdir} 下生成 %{name}.conf 文件 -- 配置文件的内容为一行或多行相同类型的配置： - ``` - // d 规定如果目录不存在则创建路径，可以有多种类型 - // /run/NAME 需要创建的文件系统路径 - // PERM 创建目录时的目录权限 - // USER 目录的所有者 - // GROUP 目录所在组的名称 - // - 自动清理在指定时间内未使用的文件 - d /run/NAME PERM USER GROUP - - ``` - -- 举例： - ``` - // 查询 %{_tmpfilesdir} 对应的实际路径 - [root@localhost ~]$ rpm -E %{_tmpfilesdir} - /usr/lib/tmpfiles.d - - // 查看 /usr/lib/tmpfiles.d 下存在哪些文件 - [root@localhost ~]$ ll /usr/lib/tmpfiles.d/x11.conf - -rw-r--r--. 1 root root 617 3月 11 15:33 /usr/lib/tmpfiles.d/x11.conf - - // 案例1: - [root@localhost ~]$ cat /usr/lib/tmpfiles.d/cryptsetup.conf - d /run/cryptsetup 0700 root root - - - // 案例2: - [root@localhost ~]$ cat /usr/lib/tmpfiles.d/dnf.conf - // Unlink the dnf lock files during boot - R /var/tmp/dnf*/locks/* - r /var/cache/dnf/download_lock.pid - r /var/cache/dnf/metadata_lock.pid - r /var/lib/dnf/rpmdb_lock.pid - r /var/log/log_lock.pid - ``` - -##### 2.5.4.9 locale 文件 - -rpm 提供了 %find_lang 宏用于处理 locale 文件，%find_lang 能够按名称扫描软件包中所有的 locale 文件，并将列表放入文件中，然后可以通过该文件来打包所有的locale文件。 -使用方式： 在 %install 阶段将所有的文件都安装到 %buildroot 后，运行 %find_lang ，并在 %files 阶段将文件打入 rpm。 -``` -%install -....... -%find_lang %{name} - -%files -f %{name}.lang -...... -``` - 如果 lang 文件与 %{name} 不同，则需要单独调用 %find_lang 脚本 -``` -%install -....... -%find_lang %{name} -%find_lang test --with-man - -%files -f %{name}.lang -f test.lang -...... -``` - -##### 2.5.4.10 cron 文件 - -cron 文件的存放目录取决于运行时的间隔，可能的目录有： -``` -[root@localhost ~]$ ll /etc/ | grep cron --rw-r--r--. 1 root root 541 Jan 26 2021 anacrontab -drwxr-xr-x. 2 root root 4096 Jun 27 2021 cron.d -drwxr-xr-x. 2 root root 4096 Jun 27 2021 cron.daily --rw-r--r--. 1 root root 0 Jan 26 2021 cron.deny -drwxr-xr-x. 2 root root 4096 Jun 27 2021 cron.hourly -drwxr-xr-x. 2 root root 4096 Jun 16 2021 cron.monthly --rw-r--r--. 1 root root 451 Jun 16 2021 crontab -drwxr-xr-x. 2 root root 4096 Jun 16 2021 cron.weekly -``` -例外情况：如果某个 cron 的任务的运行频率或者时间间隔不满足上述规定的间隔，则需要自定义 crontab 文件添加到 /etc/cron.d（具有 0640 权限)）, cron 任务文件（脚本）必须放在适当的系统位置（例如 %{_sbindir}、%{_libexecdir}），而不是 /etc/cron.d。 - -##### 2.5.4.11 头文件 -当我们使用某款软件做开发时，会依赖其对外提供的头文件，这些头文件在系统中的位置一般都是 %{_includedir}( /usr/include )，并且会被封装到 devel 包中，同时 devel 包对于主包是存在运行依赖关系的。 -``` -[root@localhost ~]$ rpm -ql zlib-devel -/usr/include/zconf.h -/usr/include/zlib.h -..... -``` - -##### 2.5.4.12 pkgconfig 文件 - -一般伴随头文件的还有一个 pkgconfig 文件，在系统中的位置为 /usr/lib64/pkgconfig，一般以 %{name}.pc 文件存在，对外提供 pkgconfig(%{name}) 功能。 -``` -[root@localhost ~]$ rpm -ql zlib-devel -...... -/usr/lib64/pkgconfig/zlib.pc -...... - -// 查询对外提供的 pkgconfig 能力 -[root@localhost ~]$ rpm -qP zlib-devel -pkgconfig(zlib) = 1.2.11 -zlib-devel = 1.2.11-1.an23 -zlib-devel(x86-64) = 1.2.11-1.an23 -``` - -##### 2.5.4.13 example 文件 - -一般软件的源码中会包含一些测试文档和样本文件，我们也需要将这些 example 文件打入 devel 包中，存在系统的位置为：/usr/share/doc/%{package}-devel/example*，一般源码中会包含 examples 目录，我们也可以将 examples 目录都打入。 -``` -[root@localhost ~]$ rpm -ql zlib-devel -...... -/usr/share/doc/zlib-devel/example.c -...... - -[root@localhost zlib-1.2.11]$ ll -...... -drwxr-xr-x 2 501 games 4096 Aug 8 22:48 examples -...... -``` - -##### 2.5.4.14 doc 文件 - -一般软件源码中也会包含一些说明性质的文档，来讲述软件的基本功能、修改记录、软件计划节奏等。 -包括不限制：readme、changelog、news、todo 等。 - - -### 2.6 脚本执行 - -在 spec 中除了定义上述中的编译、安装、打包外，还有额外的脚本操作，这些脚本是按照 rpm 安装或者卸载的顺序来执行，一方面是为了准备安装或者卸载所需要的环境条件，另一方面是为了满足软件的运行需求。 -一般将脚本定义在 %install 和 %files 中间的位置。 - -#### 2.6.1 %pre - -%pre 是代表 rpm 安装之前所执行的脚本。 -格式如下：在 pre 之后可以定义在具体 rpm 所执行的内容，如果 rpm 为重命名的，需要同样采用 -n 选项 -``` -%pre rpm_name -xxxx - -%pre -n rpm_name -xxxx -``` -样例：dbus 生成的 dbus-daemon.rpm 需要设置 dbus 的用户群组 -``` -%install -...... - -%pre daemon -// Add the "dbus" user and group -getent group dbus >/dev/null || groupadd -f -g %{dbus_user_uid} -r dbus -if ! getent passwd dbus >/dev/null ; then - if ! getent passwd %{dbus_user_uid} >/dev/null ; then - useradd -r -u %{dbus_user_uid} -g %{dbus_user_uid} -d '/' -s /sbin/nologin -c "System message bus" dbus - else - useradd -r -g %{dbus_user_uid} -d '/' -s /sbin/nologin -c "System message bus" dbus - fi -fi -exit 0 - - -...... -%files -``` - -#### 2.6.2 %post - -%post 用来声明 rpm 安装后执行的脚本。 -样例：在 dbus 的 spec 内，对dbus-comon 安装后需要将对应的服务启动。 -``` -%post common -%systemd_post dbus.socket -%systemd_user_post dbus.socket -``` - -#### 2.6.3 %preun - -%preun 用来声明 rpm 卸载之前执行的脚本。 -样例：在 dbus 的 spec 内，对dbus-comon 安装后需要将对应的服务关闭。 -``` -%preun common -%systemd_preun dbus.socket -%systemd_user_preun dbus.socket -``` - -#### 2.6.4 %postun - -%postun 用来声明 rpm 卸载之后执行的脚本。 -样例： -``` -%postun common -%systemd_postun dbus.socket -%systemd_user_postun dbus.socket -``` - -#### 2.6.5 脚本执行顺序 - -- 单个 rpm 的脚本执行顺序： - - ``` - // 安装动作 - %pre 脚本 -》 安装文件 -》执行 %post 脚本 - - // 卸载动作 - %preun 脚本 -》 删除文件 -》执行 %postun 脚本 - ``` - -- rpm 升级时的脚本执行顺序: - - ![](../images/306-scripts-execution-order-during-rpm-upgrade.jpeg) - - -#### 2.6.6 执行状态判断 - -因为在首次安装或升级时，都要去执行 pre 或 post 操作，为了区分不同的前提状态，脚本里默认增加了变量 "$1" ，在脚本对应阶段通过 "$1" 的判断在安装和升级阶段执行不同的脚本 - -| 软件包动作 | %pre | %post | %preun | %postun | -| --- | --- | --- | --- | --- | -| 首次安装 | "$1" = 1 | 不适用 | "$1" = 1 | 不适用 | -| 升级 | "$1" = 2 | "$1" = 1 | "$1" = 2 | "$1" = 1 | -| 卸载 | 不适用 | "$1" = 0 | 不适用 | "$1" = 0 | - - - -## 3 常见问题汇总 - -### 3.1 rpmbuild 基础知识 - -#### 3.1.1 为什么需要了解 rpmbuild ？ - -rpmbuild 提供了本地生成 rpm 的功能，可以实现从 spec + source.tar.gz 生成对应的 rpm 文件。 - -#### 3.1.2 环境初始化 - -准备 rpmbuild 的运行所需要的目录结构，通常 SOURCES 是必须的目录，其他路径在运行过程中会自动生成。 - -- 方案1 - 手动创建目录结构 - ``` - [root@localhost ~]$ mkdir rpmbuild - [root@localhost ~]$ mkdir rpmbuild/SOURCES - ``` - -- 方案2 - 通过 rpmdevtools 中的 rpmdev-setuptree 命令生成 - ``` - [root@localhost ~]$ yum install rpmdevtools - [root@localhost ~]$ rpmdev-setuptree - [root@localhost ~]$ ll rpmbuild/ - total 20 - drwxr-xr-x 2 root root 4096 Aug 15 02:12 BUILD - drwxr-xr-x 2 root root 4096 Aug 15 02:12 RPMS - drwxr-xr-x 2 root root 4096 Aug 15 02:12 SOURCES - drwxr-xr-x 2 root root 4096 Aug 15 02:12 SPECS - drwxr-xr-x 2 root root 4096 Aug 15 02:12 SRPMS - ``` - -#### 3.1.3 目录结构介绍 - -实际使用目录介绍： -``` -[root@localhost ~]$ ll /root/rpmbuild/ -总用量 0 -drwxr-xr-x. 3 root root 28 8月 9 14:54 BUILD ## 源码编译目录 -drwxr-xr-x. 2 root root 6 8月 8 14:51 BUILDROOT ## 源码预安装目录 -drwxr-xr-x. 2 root root 6 7月 28 17:48 RPMS ## rpm 产物目录 -drwxr-xr-x. 4 root root 174 8月 9 19:38 SOURCES ## 源码文件目录 -drwxr-xr-x. 2 root root 6 7月 28 17:48 SPECS ## spec 目录 -drwxr-xr-x. 2 root root 47 8月 8 14:51 SRPMS ## srpm 目录 -``` - -#### 3.1.4 安装 rpmbuild - -初始环境中不会默认安装 `/usr/bin/rpmbuild`，需要开发者自行安装 `rpm-build`软件。 -``` -[root@localhost ~]$ yum install rpm-build -``` - -#### 3.1.5 使用介绍 - -rpmbuild 针对 spec 里的每一个阶段都提供了对应的 option，可以方便的按需执行到对应阶段。 - -- 准备阶段 - -将 source.tar.gz 和 spec 拷贝至 SOURCES 目录后，执行 rpmbuild 命令会生成其他目录结构。 - -- 构建相关的基本命令 - ``` - rpmbuild -bp xxx.spec // 执行完 %prep，解压和打补丁 - rpmbuild -bb xxx.spec // 执行完 %build，执行到编译动作结束 - rpmbuild -bi xxx.spec // 执行完 %install，执行到安装动作结束 - # srpm 是将所有 source 文件打成一个压缩包 - rpmbuild -ba xxx.spec // 全部执行，生成 srpm 和 rpm - rpmbuild -bs xxx.spec // 只生成 srpm - rpmbuild -bl xxx.spec // 检验文件是否齐全 - ``` - -- 拓展功能，以下为比较常用的选项介绍 - ``` - -buildroot=DIRECTORY // 自定义 build root 的目录 - -clean // 完成打包后清除BUILD下的文件目录 - -nobuild // 不执行 build 阶段 - -nodeps // 忽略掉构建依赖 - ``` - -### 3.2 补丁 - -#### 3.2.1 什么是补丁？ - -在源码中经常能看到后缀为 .patch 的文件，这些文件即是补丁文件。样例如下： -``` -[root@localhost tbb]$ ll -total 5360 --rw-r--r-- 1 root root 488 Jul 27 07:14 README.md --rw-r--r-- 1 root root 2677 Jul 27 07:14 tbb-2019-dont-snip-Wall.patch --rw-r--r-- 1 root root 670 Jul 27 07:14 tbb-2019-test-task-scheduler-init.patch --rw-r--r-- 1 root root 1864 Jul 27 07:14 tbb-2019-test-thread-monitor.patch --rw-r--r-- 1 root root 2639737 Jul 27 07:14 tbb-2020.3.tar.gz --rw-r--r-- 1 root root 2883 Jul 27 07:14 tbb-2020-attributes.patch --rw-r--r-- 1 root root 2883 Jul 27 07:14 tbb-mark-empty_task-execute-with-gnu-used.patch -``` - -补丁格式详解： -总包含两大块：补丁头 + 实际修改内容。 -其中补丁头用于描述补丁的基本信息，查看这里就能清楚的获取补丁的制作人、制作时间和实现的功能。 -实际修改内容中包括：修改的文件路径 + 内容 -修改文件这里是默认采用源码包解压后的第一层目录作为相对目录进行，通常在打入补丁时采用 -px 来指定忽略 x 层路径。 -``` -From git log 信息 -From: patch 制作者 -Date: patch 的生成日期 -Subject: 修改的简要描述 - ---- - git diff 生成的文件差异信息 - -diff --git 修改前文件路径 修改后文件路径 ---- 修改前文件路径 -+++ 修改后文件路径 -@@ index @@ index 对应的代码行 -实际代码 -``` -样例： - -``` -[root@localhost tbb]$ cat tbb-mark-empty_task-execute-with-gnu-used.patch -From db2f2116adfb545bb76c92205f91e3e3f0f9e44a Mon Sep 17 00:00:00 2001 -From: Thomas Rodgers -Date: Wed, 2 Jun 2021 15:18:30 -0700 -Subject: [PATCH] Mark tbb::empty_task::execute with [[gnu::used]] - ---- - include/tbb/task.h | 3 +++ - 1 file changed, 3 insertions(+) - -diff --git a/include/tbb/task.h b/include/tbb/task.h -index 5e137c6..5b60163 100644 ---- a/include/tbb/task.h -+++ b/include/tbb/task.h -@@ -1040,6 +1040,9 @@ inline void task::resume(suspend_point tag) { - //! task that does nothing. Useful for synchronization. - /** @ingroup task_scheduling */ - class __TBB_DEPRECATED_IN_VERBOSE_MODE empty_task: public task { -+#if __has_cpp_attribute(gnu::used) -+ [[gnu::used]] -+#endif - task* execute() __TBB_override { - return NULL; - } --- -2.31.1 -``` - -#### 3.2.2 为什么要有补丁文件？ - -因为 OS 体系是由众多第三方开源软件组成的，这些第三方开源软件都是有自己的维护者的。 -那么 Anolis OS 作为发行者的角色，只能从开源社区取到完整的 source.tar.gz，这些 source.tar.gz 是不允许直接解压开直接修改的，所以针对 source.tar.gz 所有的修改都要通过 patch 的途径进行。 - -#### 3.2.3 如何制作补丁？ - -- 首先，将源码包解压开，如果有前缀补丁，需要将其先打入。 - - ``` - // 先将源代码拷贝到 ～/rpmbuild/SOURCES/ - [root@localhost tbb]$ cp * /root/rpmbuild/SOURCES/ - - // 执行解压动作 - [root@localhost tbb]$ rpmbuild -bp tbb.spec --nodeps - Executing(%prep): /bin/sh -e /var/tmp/rpm-tmp.W4Pc3T - + umask 022 - + cd /root/rpmbuild/BUILD - + cd /root/rpmbuild/BUILD - + rm -rf oneTBB-2021.5.0 - + /usr/bin/gzip -dc /root/rpmbuild/SOURCES/v2021.5.0.tar.gz - + /usr/bin/tar -xof - - + STATUS=0 - + '[' 0 -ne 0 ']' - + cd oneTBB-2021.5.0 - + /usr/bin/chmod -Rf a+rX,u+w,g-w,o-w . - + sed -i 's/version\s*="0.2"/version = "2021.5"/' python/setup.py - + sed -i '1{/^#!.*env python/ d}' python/TBB.py python/tbb/__init__.py python/tbb/__main__.py python/tbb/pool.py python/tbb/test.py - + exit 0 - ``` - -- 进入解压后的目录下，进行 git 初始化 - - ``` - // 这里 v2021.5.0.tar.gz 解压完后的目录名称为 oneTBB-2021.5.0 - [root@localhost tbb]$ cd /root/rpmbuild/BUILD/oneTBB-2021.5.0/ - - // 执行 git 初始化 - [root@localhost oneTBB-2021.5.0]$ git init - Initialized empty Git repository in /root/rpmbuild/BUILD/oneTBB-2021.5.0/.git/ - [root@localhost oneTBB-2021.5.0]$ git add . - [root@localhost oneTBB-2021.5.0]$ git commit -m "init" - ``` - -- 此时可以按照自己需要修改源码，修改之后通过 `git status` 或 `git diff`查看修改内容，如果想把多处修改合并到一个 patch 里，此处可以将要修改的文件都改了。 - - ``` - // 这里样例就随意修改了～ - [root@localhost oneTBB-2021.5.0]$ git status - On branch master - Changes not staged for commit: - (use "git add ..." to update what will be committed) - (use "git restore ..." to discard changes in working directory) - modified: README.md - - no changes added to commit (use "git add" and/or "git commit -a") - ``` - -- 提交本地修改 - - ``` - [root@localhost oneTBB-2021.5.0]$ git add . - [root@localhost oneTBB-2021.5.0]$ git commit -m "modify the README.md" - [master 171249b] modify the README.md - 1 file changed, 5 insertions(+) - ``` - -- 生成补丁，HEAD^ 代表将最近的 一次生成补丁，-o 后面为补丁输出路径。 - - ``` - [root@localhost oneTBB-2021.5.0]$ git format-patch -n HEAD^ -o /root/rpmbuild/SOURCES/ - /root/rpmbuild/SOURCES/0001-modify-the-README.md.patch - ``` - -- 查看补丁内容 - - ``` - root@localhost oneTBB-2021.5.0]$ cat /root/rpmbuild/SOURCES/0001-modify-the-README.md.patch - From 171249bd0bf1641b52697710d399d832d1b85914 Mon Sep 17 00:00:00 2001 - From: "xxx.test" - Date: Wed, 10 Aug 2022 05:22:25 -0400 - Subject: [PATCH 1/1] modify the README.md - README.md | 5 +++++ - 1 file changed, 5 insertions(+) - diff --git a/README.md b/README.md - index dd5156f..b024027 100644 - --- a/README.md - +++ b/README.md - @@ -4,6 +4,11 @@ - oneAPI Threading Building Blocks (oneTBB) lets you easily write parallel C++ programs that take xxxxxxxx - full advantage of multicore performance, that are portable, composable and have future-proof scalability. - - +############## - +this is test - +############## - + - + - #### Release Information - Here are [Release Notes]( https://software.intel.com/en-us/articles/intel-oneapi-threading-building-blocks-release-notes) and - [System Requirements](https://software.intel.com/en-us/articles/intel-oneapi-threading-building-blocks-system-requirements). - -- - 2.27.0 - ``` - - - -#### 3.2.4 如何打补丁？ - -- 源码方式打入补丁 - - 可以通过 `git apply`命令在源码中将补丁打入 - - ``` - // 解压源码，并将以前补丁打入 - [root@localhost SOURCES]$ rpmbuild -bp tbb.spec --nodeps - - // 进入解压后的目录 - [root@localhost SOURCES]$ cd /root/rpmbuild/BUILD/oneTBB-2021.5.0/ - - // 检查补丁 - [root@localhost oneTBB-2021.5.0]$ git apply --check /root/rpmbuild/SOURCES/0001-modify-the-README.md.patch - - // 打入补丁 - [root@localhost oneTBB-2021.5.0]$ git apply /root/rpmbuild/SOURCES/0001-modify-the-README.md.patch - ``` - -- 通过 spec 方式打入补丁 - - 参见 2.2 章节中的 %prep 介绍。 - -### 3.3 构建问题 - -#### 3.3.1 构建环境是什么？ - -构建环境是一个相对“干净”的环境，因为是从 chroot 生成的，该环境仅仅用于源码构建，不用于其他用途。 - -#### 3.3.2 构建环境里安装的软件是在哪里指定的？ - -构建环境是来源于两处：**默认安装** + **spec 中 BuildRequires 指定**。默认安装是我们针对所有软件包构建的一个基础编译环境，只包含编译工具链的软件；每个软件可以将自己构建需要引入的软件包都写到 BuildRequires 中，则构建环境会去安装这些软件，从而共同组成了构建环境。 - -#### 3.3.3 我如果想在构建环境中增加软件，该如何做？ - -在编译的过程中，经常会遇到缺少某个头文件或者某个动态库，再或者某个二进制的情况，这是我们需要将缺少的文件所属的 rpmpackage 添加到 BuildRequires 中，然后重新发起构建即可。 -举例： 假设当前缺少 /usr/include/ncursesw/etip.h，可以通过 `dnf`查询改文件的所属，并将该软件写到 BuildRequires 中。 -``` -$ dnf repoquery --whatprovides '/usr/include/ncursesw/etip.h' -上次元数据过期检查：1:26:21 前，执行于 2022年08月10日 星期三 12时45分43秒。 -ncurses-devel-0:6.3-2.an23.x86_64 -``` - -#### 3.3.4 在构建环境里的软件版本不满足我的需求怎么办？ - -软件（A）包在构建的过程中，可能需要指定某个构建依赖包（B）的版本的版本号，这时发现构建环境里安装的这款软件和预期版本不满足，此时，需要我们先把依赖包准备出对应的 rpm 后，再来编译原本的软件。 - -- B 大于 A - -这种场景下优先建议 A 软件进行适配 B 软件。因为高版本的 B 软件已经发布，整个 OS 内的其他软件已经依赖了高版本的 B，降级和多版本共存的场景都不满足 OS 发行版的要求，而且从软件的长远发展路线来看，去适配最新版本也是最好的选择。 - -- B 小于 A - -这种场景下建议先将软件包 B 进行基线升级，升级到满足 A 的要求的版本，但是进行基线升级时，需要进行全面的影响评估，请勿对其他软件产生影响。 - -#### 3.3.5 我需要在构建环境中执行外网操作怎么办？ - -结论：不允许出现访问外网操作。 -因为构建环境是一个模拟的chroot中构建的，无法访问互联网，同时也不允许从外网直接下载依赖的操作，这里的外网操作包括但不限制如下：配置境外、国内的任何一个远端源（pip、nodejs、rust、maven 等），wget 下载、curl 下载等等。 - -#### 3.3.6 如果我必须下载很多外部源怎么办？ - -对于还在孵化期的软件，我们允许将所有构建依赖下载到本地，然后通过 offline 模式指定本地的路径进行编译。但该动作需要得到 OS 产品接口人的许可，方可执行。 -当前以 go 语言举例，其他语言参照 - -- 先在联网环境下，进入到源代码目录下，下载对应的依赖，并放到本地的 vendor 目录下 -``` -go mod vendor -``` - -- 关闭互联网，然后执行离线构建（这里需要根据不同语言，选择不同的离线方式） -``` -go build -mod=vendor -``` - -- 在上述两步执行成功之后，将 vendor 目录生成压缩包，作为 spec 的第二个source，并将离线构建方式写入 - - ``` - ...... - Source0: package.tar.gz - Source1: package_vendor.tar.gz - ....... - - - %prep - %autosetup -n %{name}-%{release} - tar -xvf %{SOURCE1} ./ - - %build - go build -mod=vendor - ``` - -- rpmbuild 构建或者 koji 构建测试，待成功后提交代码 - -#### 3.3.7 构建过程中提示没有权限怎么办？ - -当构建过程中提示权限不足时，第一想法都是怎么去提高构建权限，这种想法是不对的。因为，所有发行版的正式构建都是以 build 用户执行的，是不允许操作系统环境的，只允许在构建目录下操作。 -所以，应该去排查是哪里操作了系统目录，然后将该动作的修改到构建目录下。 diff --git a/TECHNOLOGY_DOCS/GITEE/307-build-a-new-project.md b/TECHNOLOGY_DOCS/GITEE/307-build-a-new-project.md deleted file mode 100644 index e69de29bb2d1d6434b8b29ae775ad8c2e48c5391..0000000000000000000000000000000000000000 diff --git a/TECHNOLOGY_DOCS/GITEE/308-example-of-epao-nonfree-package.md b/TECHNOLOGY_DOCS/GITEE/308-example-of-epao-nonfree-package.md deleted file mode 100644 index 72c9ce82d021b1f210f197d358609fa727d579e7..0000000000000000000000000000000000000000 --- a/TECHNOLOGY_DOCS/GITEE/308-example-of-epao-nonfree-package.md +++ /dev/null @@ -1,327 +0,0 @@ -# 闭源软件集成样例 - -### 1. 联系法务，走开源流程 - -acc 的软件维护者 程斌 同学，在准备好公开策略（公开的频率和方式）之后，联系法务同学，申请了二进制披露序和开源软件合规扫描。这里要注意一点，如果涉及版本更新，则该流程需要重新走一遍。 - -### 2. 获取法律允许 - -流程申请之后，获取法务许可，增加一个 Alibaba-Cloud-Compiler-End-User-Agreement.docx 文件，该文件表示用户安装此软件的同意许可。该文件和软件本身的 License 文件必须包含在 rpm 的 filelist 内。 - -### 3. 本地准备编译环境，制作可用 rpm，并进行本地测试。 - -1. 需要定义软件的基本信息。 - - -2. 包括：name、version、summary、url、descriotion。 - -3. 注意：version 代表软件版本，release 仅代表构建次数。如果同一个版本，不做源码变更（此处叫二进制变更），仅仅是 spec 的修改，需要保证 version 不变、递增 release；如果在正式发布之后版本发生变更，比如二进制更新了，此处应该变更 version，release 重新从 1 开始。 - - -4. 软件维护者准备编译环境。 - - -5. 发布的版本尽量和本地的构建环境保持一致，因为构建依赖的版本不同可能会导致 so 运行不起来。即：发布到 Anolis OS 23 的 rpm 尽量使用 Anolis OS 23 的环境编译，发布到 Anolis OS 8 的 rpm 尽量使用 Anolis OS 8 的环境进行编译。 - -6. acc 这个包比较特殊，特殊在仅对 glibc 的 so 有依赖，且 an8 提供的 glibc.so 在 Anolis OS 23 上也能通用，所以仅构建一次，采用 Anolis OS 8 上构建出来的结果同步发布到 Anolis OS 23 版本。 - - -7. 新建 spec（[参考 spec 模版](https://gitee.com/anolis/docs/blob/main/articles/305-module-and-checklist-of-spec.md)），并在本地编译出闭源软件的 rpm。 - -8. rpmbuild 过程出现问题，可以查看 [构建指导手册](../articles/306-instruction-manual-of-rpmbuild.md) - -9. 此处直接给出 rpm 样例： - -``` - [root@localhost acc]# ls - alibaba-cloud-compiler-13.0.1-2.fix.an8.aarch64.rpm - alibaba-cloud-compiler-13.0.1-2.fix.an8.src.rpm - alibaba-cloud-compiler-13.0.1-2.fix.an8.x86_64.rpm -``` - -### 4. 制作 rpm tree 需要的 source 文件。 - -* 需要先创建一个目录（rpmname-version），并且在该目录下创建两个架构目录（x86\_64，aarch64），如果是 noarch 的包，可以建立 noarch 目录或者选择不建立架构目录。 - -``` - [root@localhost acc]# mkdir alibaba-cloud-compiler-13.0.1 - [root@localhost acc]# cd alibaba-cloud-compiler-13.0.1 - [root@localhost alibaba-cloud-compiler-13.0.1]# mkdir x86_64 - [root@localhost alibaba-cloud-compiler-13.0.1]# mkdir aarch64 - [root@localhost alibaba-cloud-compiler-13.0.1]# ls - aarch64 x86_64 - [root@localhost acc]# tree alibaba-cloud-compiler-13.0.1 - alibaba-cloud-compiler-13.0.1 - ├── aarch64 - └── x86_64 - - 3 directories, 0 files -``` - -* 使用 rpm2cpio 命令将 rpm 解压到刚才创建的带架构的目录下。（注意：路径全部保留）-D 选项可以指定解压的目标目录。 - -``` - [root@localhost acc]# rpm2cpio alibaba-cloud-compiler-13.0.1-2.fix.an8.x86_64.rpm | cpio -divm -D alibaba-cloud-compiler-13.0.1/x86_64 - [root@localhost acc]# ls alibaba-cloud-compiler-13.0.1 - aarch64 x86_64 - [root@localhost acc]# ls alibaba-cloud-compiler-13.0.1/x86_64/ - opt - [root@localhost acc]# ls alibaba-cloud-compiler-13.0.1/x86_64/opt/ - alibaba-cloud-compiler - [root@localhost acc]# ls alibaba-cloud-compiler-13.0.1/x86_64/opt/alibaba-cloud-compiler/ - bin FLANG-LICENSE.TXT include JEMALLOC.COPYING lib64 libexec LICENSE.TXT README share -``` - -* 将另一个架构的 rpm 按照同样方式解压拷贝进去。 - -``` - [root@localhost acc]# tar -xvf 20221117-161007-543-#75-anolis8.6.aarch64.release.rpm-13-rpm.tar.gz - alibaba-cloud-compiler-13.0.1-2.fix.an8.aarch64.rpm - alibaba-cloud-compiler-13.0.1-2.fix.an8.src.rpm - summary_message.txt - [root@localhost acc]# rpm2cpio alibaba-cloud-compiler-13.0.1-2.fix.an8.aarch64.rpm | cpio -divm -D alibaba-cloud-compiler-13.0.1/aarch64/ - [root@localhost acc]# ls alibaba-cloud-compiler-13.0.1/aarch64/opt/alibaba-cloud-compiler/ - bin FLANG-LICENSE.TXT include JEMALLOC.COPYING lib64 libexec LICENSE.TXT README share -``` - -* 对整个目录进行压缩，压缩成一个 tar.gz - -``` - [root@localhost acc]# tar -cvf alibaba-cloud-compiler-13.0.1.tar.gz alibaba-cloud-compiler-13.0.1 - [root@localhost acc]# ls | grep tar.gz - 20221117-161007-047-#75-anolis8.6.x86_64.release.rpm-13-rpm.tar.gz - 20221117-161007-543-#75-anolis8.6.aarch64.release.rpm-13-rpm.tar.gz - alibaba-cloud-compiler-13.0.1.tar.gz -``` - -### 5. 走软件引入流程，ospkg-list 进行申请 - -* 软件维护者创建 issue，按照模版填写需求背景、收益、维护者和目标。写清楚闭源软件的引入背景和原因、闭源的 License 信息等。 - -* 由橘悦审核 issue 并通过之后，进行建立仓库。仓库地址：https://gitee.com/src-anolis-nonfree/ , a8 分支对应 Anolis OS 8，a23 分支对应 Anolis OS 23。 - -* 软件维护者在 ospkg-list 仓库中提交代码，参照指导，提交软件信息 - - -### 6. 将制作好的 source.tar.gz 和 spec 提交到已经建立的仓库 - -* 打开 gitee 的仓库地址：https://gitee.com/src-anolis-nonfree/  - -* 将软件仓库 fork 到个人仓库 - -* 将准备好的 source.tar.gz 和 spec 文件提交到个人仓库的版本分支（a8或a23） - -* 发起 pr，等待门禁通过，如果门禁失败，则需要查看错误原因，并进行解决，重新提交代码后，门禁会重新触发 - -* 提交者下载门禁构建的 rpm 包，并自行进行功能测试 - -* 等待 maintainer 或者发行版同学审核通过，合入代码，由发行版同学触发正式构建 - -* 发行版同学将 rpm 发布到 epao-nonfree 仓库，维护者安装 anolis-epao-nonfree-release 包之后，即可通过 yum install 的方式进行安装对应闭源组件。 - - -### 7. 软件和代码样例 - -#### 软件样例： - -alibaba-cloud-compiler - -#### 代码样例： - -* spec 样例：[https://gitee.com/src-anolis-sig/alibaba-cloud-compiler/blob/a23/alibaba-cloud-compiler.spec](https://gitee.com/src-anolis-sig/alibaba-cloud-compiler/blob/a23/alibaba-cloud-compiler.spec) - -* source 样例：[http://build.openanolis.cn/kojifiles/upstream-source/alibaba-cloud-compiler-13.0.1.3.tar.gz.c2df8c535fc55ac9604cc2f3b16cbc60](http://8.131.87.1//kojifiles/upstream-source/alibaba-cloud-compiler-13.0.1.3.tar.gz.c2df8c535fc55ac9604cc2f3b16cbc60) - - -#### 门禁 CI 的检测内容样例： - -##### 1. 将 rpm 解压到本地 - - [root@localhost acc]# ls - 20221117-161007-047-#75-anolis8.6.x86_64.release.rpm-13-rpm.tar.gz summary_message.txt - 20221117-161007-543-#75-anolis8.6.aarch64.release.rpm-13-rpm.tar.gz - [root@localhost acc]# tar -xvf 20221117-161007-047-#75-anolis8.6.x86_64.release.rpm-13-rpm.tar.gz - alibaba-cloud-compiler-13.0.1-2.fix.an8.src.rpm - alibaba-cloud-compiler-13.0.1-2.fix.an8.x86_64.rpm - -##### 2. 测试基本安装和卸载 - -* 安装测试：如果采用 rpm 安装显示缺少运行依赖时，可以采用 yum localinstall 方式进行验证。 - -``` - [root@localhost acc]# ls - 20221117-161007-047-#75-anolis8.6.x86_64.release.rpm-13-rpm.tar.gz alibaba-cloud-compiler-13.0.1-2.fix.an8.x86_64.rpm - 20221117-161007-543-#75-anolis8.6.aarch64.release.rpm-13-rpm.tar.gz summary_message.txt - alibaba-cloud-compiler-13.0.1-2.fix.an8.src.rpm - [root@localhost acc]# rpm -ivh alibaba-cloud-compiler-13.0.1-2.fix.an8.x86_64.rpm - error: Failed dependencies: - perl(File::Copy) is needed by alibaba-cloud-compiler-13.0.1-2.fix.an8.x86_64 - perl(FindBin) is needed by alibaba-cloud-compiler-13.0.1-2.fix.an8.x86_64 - perl(Hash::Util) is needed by alibaba-cloud-compiler-13.0.1-2.fix.an8.x86_64 - perl(Sys::Hostname) is needed by alibaba-cloud-compiler-13.0.1-2.fix.an8.x86_64 - [root@localhost acc]# yum localinstall alibaba-cloud-compiler-13.0.1-2.fix.an8.x86_64.rpm - Last metadata expiration check: 0:42:27 ago on Thu 03 Aug 2023 01:18:16 PM CST. - Dependencies resolved. - ===================================================================================================================================== - Package Architecture Version Repository Size - ===================================================================================================================================== - Upgrading: - perl-Errno x86_64 1.36-11.an23 os 14 k - perl-interpreter x86_64 4:5.36.1-11.an23 os 70 k - perl-libs x86_64 4:5.36.1-11.an23 os 2.1 M - Installing dependencies: - perl-File-Copy noarch 2.39-11.an23 os 19 k - perl-FindBin noarch 1.53-11.an23 os 13 k - perl-Hash-Util x86_64 0.28-11.an23 os 33 k - perl-Hash-Util-FieldHash x86_64 1.26-11.an23 os 37 k - perl-Sys-Hostname x86_64 1.24-11.an23 os 16 k - Downgrading: - alibaba-cloud-compiler x86_64 13.0.1-2.fix.an8 @commandline 651 M - - Transaction Summary - ===================================================================================================================================== - Install 5 Packages - Upgrade 3 Packages - Downgrade 1 Package - - Total size: 653 M - Total download size: 2.3 M - Is this ok [y/N]: y - Downloading Packages: - (1/8): perl-FindBin-1.53-11.an23.noarch.rpm 60 kB/s | 13 kB 00:00 - (2/8): perl-Hash-Util-0.28-11.an23.x86_64.rpm 127 kB/s | 33 kB 00:00 - (3/8): perl-File-Copy-2.39-11.an23.noarch.rpm 69 kB/s | 19 kB 00:00 - (4/8): perl-Hash-Util-FieldHash-1.26-11.an23.x86_64.rpm 260 kB/s | 37 kB 00:00 - (5/8): perl-Sys-Hostname-1.24-11.an23.x86_64.rpm 105 kB/s | 16 kB 00:00 - (6/8): perl-Errno-1.36-11.an23.x86_64.rpm 82 kB/s | 14 kB 00:00 - (7/8): perl-interpreter-5.36.1-11.an23.x86_64.rpm 551 kB/s | 70 kB 00:00 - (8/8): perl-libs-5.36.1-11.an23.x86_64.rpm 4.3 MB/s | 2.1 MB 00:00 - ------------------------------------------------------------------------------------------------------------------------------------- - Total 2.6 MB/s | 2.3 MB 00:00 - Running transaction check - Transaction check succeeded. - Running transaction test - Transaction test succeeded. - Running - Preparing : 1/1 - Upgrading : perl-libs-4:5.36.1-11.an23.x86_64 1/13 - Installing : perl-File-Copy-2.39-11.an23.noarch 2/13 - Installing : perl-FindBin-1.53-11.an23.noarch 3/13 - Installing : perl-Hash-Util-FieldHash-1.26-11.an23.x86_64 4/13 - Installing : perl-Hash-Util-0.28-11.an23.x86_64 5/13 - Installing : perl-Sys-Hostname-1.24-11.an23.x86_64 6/13 - Upgrading : perl-interpreter-4:5.36.1-11.an23.x86_64 7/13 - Downgrading : alibaba-cloud-compiler-13.0.1-2.fix.an8.x86_64 8/13 - Upgrading : perl-Errno-1.36-11.an23.x86_64 9/13 - Cleanup : perl-Errno-1.36-10.an23.x86_64 10/13 - Cleanup : perl-interpreter-4:5.36.0-10.an23.x86_64 11/13 - Cleanup : perl-libs-4:5.36.0-10.an23.x86_64 12/13 - Cleanup : alibaba-cloud-compiler-13.0.1.3-1.an23.x86_64 13/13 - Running scriptlet: alibaba-cloud-compiler-13.0.1.3-1.an23.x86_64 13/13 - Verifying : alibaba-cloud-compiler-13.0.1-2.fix.an8.x86_64 1/13 - Verifying : alibaba-cloud-compiler-13.0.1.3-1.an23.x86_64 2/13 - Verifying : perl-File-Copy-2.39-11.an23.noarch 3/13 - Verifying : perl-FindBin-1.53-11.an23.noarch 4/13 - Verifying : perl-Hash-Util-0.28-11.an23.x86_64 5/13 - Verifying : perl-Hash-Util-FieldHash-1.26-11.an23.x86_64 6/13 - Verifying : perl-Sys-Hostname-1.24-11.an23.x86_64 7/13 - Verifying : perl-Errno-1.36-11.an23.x86_64 8/13 - Verifying : perl-Errno-1.36-10.an23.x86_64 9/13 - Verifying : perl-interpreter-4:5.36.1-11.an23.x86_64 10/13 - Verifying : perl-interpreter-4:5.36.0-10.an23.x86_64 11/13 - Verifying : perl-libs-4:5.36.1-11.an23.x86_64 12/13 - Verifying : perl-libs-4:5.36.0-10.an23.x86_64 13/13 - - Upgraded: - perl-Errno-1.36-11.an23.x86_64 perl-interpreter-4:5.36.1-11.an23.x86_64 perl-libs-4:5.36.1-11.an23.x86_64 - Downgraded: - alibaba-cloud-compiler-13.0.1-2.fix.an8.x86_64 - Installed: - perl-File-Copy-2.39-11.an23.noarch perl-FindBin-1.53-11.an23.noarch perl-Hash-Util-0.28-11.an23.x86_64 - perl-Hash-Util-FieldHash-1.26-11.an23.x86_64 perl-Sys-Hostname-1.24-11.an23.x86_64 - - Complete! -``` - -* 卸载测试： - - * 卸载时不仅要测试包有没有卸载掉，更需要确认安装的文件或者路径是否被清除。 - - * 这个版本的 acc 在卸载时文件虽然被清除干净，但是路径没清除，该问题需要解决。解决方案：在 %files 中增加对路径的定义: - -``` -%files - -%dir /opt - -%dir /opt/alibaba-cloud-compiler -``` -``` - # - [root@localhost acc]# rpm -ql alibaba-cloud-compiler | grep txt - /opt/alibaba-cloud-compiler/lib64/clang/13.0.1/share/asan_ignorelist.txt - /opt/alibaba-cloud-compiler/lib64/clang/13.0.1/share/cfi_ignorelist.txt - /opt/alibaba-cloud-compiler/lib64/clang/13.0.1/share/dfsan_abilist.txt - /opt/alibaba-cloud-compiler/lib64/clang/13.0.1/share/hwasan_ignorelist.txt - /opt/alibaba-cloud-compiler/lib64/clang/13.0.1/share/msan_ignorelist.txt - [root@localhost acc]# rpm -qa alibaba-cloud-compiler - alibaba-cloud-compiler-13.0.1-2.fix.an8.x86_64 - [root@localhost acc]# rpm -e alibaba-cloud-compiler - [root@localhost acc]# rpm -qa alibaba-cloud-compiler - [root@localhost acc]# ls ///opt/alibaba-cloud-compiler/lib64/ - #### 注意 ！！！！这里有问题！！！！ - [root@localhost acc]# ls /opt/alibaba-cloud-compiler - bin include lib64 libexec share -``` - -##### 3. 测试该软件对外提供的能力是否产生冲突 - -* 通过 rpm -qP 查看对外提供的能力，需要对每一个 Provides 的能力进行检测现有源上会不会存在同等功能，尤其是 so，一旦查出来存在相同能力即为有问题的 rpm，需要去除对应能力提供。这里可以用 libflang.so()(64bit) 举例。 - -``` - [root@localhost acc]# ls alibaba-cloud-compiler-13.0.1-2.fix.an8.x86_64.rpm - alibaba-cloud-compiler-13.0.1-2.fix.an8.x86_64.rpm - [root@localhost acc]# rpm -qP alibaba-cloud-compiler-13.0.1-2.fix.an8.x86_64.rpm - alibaba-cloud-compiler = 13.0.1-2.fix.an8 - alibaba-cloud-compiler(x86-64) = 13.0.1-2.fix.an8 - lib64/LLVMgold.so(LLVM_13)(64bit) - libRemarks.so.13()(64bit) - libRemarks.so.13(LLVM_13)(64bit) - libclang_rt.asan-x86_64.so()(64bit) - libclang_rt.dyndd-x86_64.so()(64bit) - libclang_rt.hwasan-x86_64.so()(64bit) - libclang_rt.hwasan_aliases-x86_64.so()(64bit) - libclang_rt.memprof-x86_64.so()(64bit) - libclang_rt.scudo-x86_64.so()(64bit) - libclang_rt.scudo_minimal-x86_64.so()(64bit) - libclang_rt.scudo_standalone-x86_64.so()(64bit) - libclang_rt.ubsan_minimal-x86_64.so()(64bit) - libclang_rt.ubsan_standalone-x86_64.so()(64bit) - libflang.so()(64bit) - libflangrti.so()(64bit) - libpgmath.so()(64bit) - pkgconfig(jemalloc) = 5.3.0_0 - - # 应该对每个能力进行检测，这里使用 libflang.so()(64bit） 给个样例.这里没有查到，结果正确。 - [root@localhost acc]# yum repoquery --whatprovides 'libflang.so()(64bit)' - Last metadata expiration check: 1:46:37 ago on Thu 03 Aug 2023 01:18:16 PM CST. - [root@localhost acc]# -``` -* 发现上述存在问题，去除相同能力提供方式。 - - -* 如果存在包名相同，该问题需要重新定义软件名称 - -* 如果存在提供相同的 bin ，则需要在构建时，重新创建绝对路径，将二进制存放对应目录，或者在源码中更改生成的 bin 名称，避免产生相同的 bin - -* 如果存在相同的 so，不仅需要生成到不同目录，也需要去除 so 的对外提供。 - - -spec 中添加如下代码，将其去除： -``` - %global _privatelibs (libclang.*|libflang.*|libLTO|libomp.*|libc++.*|libRemarks.*|libpgmath)[.]so.*|(.*jemalloc.*) - %global __provides_exclude ^(%{_privatelibs})$ -``` -##### 4. 准备测试文档，将上述测试都输出到测试文档中。 - -该测试文档可以添加到 pr 的评论中同步提交。 \ No newline at end of file diff --git a/TECHNOLOGY_DOCS/group.yml b/TECHNOLOGY_DOCS/group.yml deleted file mode 100644 index e69de29bb2d1d6434b8b29ae775ad8c2e48c5391..0000000000000000000000000000000000000000 diff --git a/TECHNOLOGY_DOCS/menu.yaml b/TECHNOLOGY_DOCS/menu.yaml deleted file mode 100644 index e071e053f0d001a1a9e5bc6e77c5d206cf86c889..0000000000000000000000000000000000000000 --- a/TECHNOLOGY_DOCS/menu.yaml +++ /dev/null @@ -1,20 +0,0 @@ -TECHNOLOGY_DOCS: - menu: menu.yml - maintainers: maintainers.yml - 安全管理系统: - 用户说明文档: ../安全管理系统/ANA用户API说明文档.md - 安全数据文档: ../安全管理系统/OpenAnolis安全数据API文档.md - GITEE: - 302-join-os-package-build: ../GITEE/302-join-os-package-build.md - 303: ../GITEE/303-join-kernel-developing.md - 304: ../GITEE/304-package-introduction-and-management-principles.md - 305: ../GITEE/305-module-and-checklist-of-spec.md - 306: ../GITEE/306-instruction-manual-of-rpmbuild.md - 307: ../GITEE/307-build-a-new-project.md - 308: ../GITEE/308-example-of-epao-nonfree-package.md - CSDN: - 博客园: - GITHUB: - GITLAB: - 霍格沃斯: - API开发: diff --git "a/TECHNOLOGY_DOCS/\345\256\211\345\205\250\347\256\241\347\220\206\347\263\273\347\273\237/ANA\347\224\250\346\210\267API\350\257\264\346\230\216\346\226\207\346\241\243.md" "b/TECHNOLOGY_DOCS/\345\256\211\345\205\250\347\256\241\347\220\206\347\263\273\347\273\237/ANA\347\224\250\346\210\267API\350\257\264\346\230\216\346\226\207\346\241\243.md" deleted file mode 100644 index fd2b07fd978262274b813f3e6500959d854b0c85..0000000000000000000000000000000000000000 --- "a/TECHNOLOGY_DOCS/\345\256\211\345\205\250\347\256\241\347\220\206\347\263\273\347\273\237/ANA\347\224\250\346\210\267API\350\257\264\346\230\216\346\226\207\346\241\243.md" +++ /dev/null @@ -1,1984 +0,0 @@ -## 接口描述 - -### 1). response结构 - -**1.  成功** - -```json -{ - "status": { - "code": 200, - "message": "" - }, - "data": null -} -``` - -**2. 失败** - -```json -{ - "status": { - "code": 404, - "message": "未找到。", - "redirect_url": null - }, - "data": null -} -``` - -### 2). 主要错误码 - -> 目前系统已有的，会不断完善 - - -**1). 2xx** -200 （成功） -201 （已创建） -204 （已删除） - -**2).  4xx** -400 （错误请求，针对validate error） -403 （没权限） -404 （未找到） -460 （普通错误，用于不做特殊展示的错误） - -**3). 5xx** -500（服务器发生未知错误） - -### 3). 签名算法 - -**配置说明** - -```python -# 服务器地址 -hostname = -# 服务器鉴权名称 -sys_name = -# 服务器鉴权token -token = -``` - -sys_name和token需要向[@永超(sam.zyc) ](sam.zyc@alibaba-inc.com ) 申请 - -```python -hostname = 'https://anas.openanolis.cn' -sys_name = '' -token = '' -``` - -**使用HTTP调用** - -1. 接口签名方式 -调用接口时，需要对请求进行签名，方可认证通过。接口请求需携带以下参数作为请求头： - - Timestamp：请求时间戳，单位毫秒，为发送请求时的时间（此参数会进行校验，请保证使用当前时间），300秒超时 - - Token：服务器鉴权token - - Signature：签名，请求签名 - -签名计算方法为： -`sha256(sys_name + ":" + token + ":" + timestamp)` - -2. python3 demo - -```python -import base64 -import hashlib -import requests -import time - - -class ErrataApiDemo: - """portal api demo""" - def __init__(self, hostname, sys_name, token): - self.hostname = hostname - self.sys_name = sys_name - self.token = token - - def get_sign_headers(self): - timestamp = str(round(time.time() * 1000)) - sign_items = [self.sys_name, self.token, timestamp] - hash_obj = hashlib.sha256() - hash_obj.update(':'.join(sign_items).encode('utf-8')) - signature = hash_obj.digest() - signature = base64.b64encode(signature) - return {'Timestamp': timestamp, 'Token': self.token, 'Signature': signature} - - def get_errata_list(self): - headers = {} - headers.update(self.get_sign_headers()) - params = { - 'page_num': 1, - 'page_size': 20 - } - resp = requests.get('{}/api/v1/errata/'.format(self.hostname), params=params, headers=headers, verify=False) - if resp.ok: - resp_data = resp.json() - if resp_data['status']['code'] == 200: - return resp_data['data'] - - -if __name__ == '__main__': - protal_client = Portal('https://errata.openanolis.cn', 'test', 'xxxxxxxxxxxxx') - errata_list = protal_client.get_errata_list() - print(errata_list) -``` - -返回： - -```json -{ - "total": 5, - "page_num": 1, - "total_page": 1, - "page_size": 20, - "previous": null, - "next": null, - "data": [ - { - "id": 7, - "gmt_created": "2022-01-04 12:20:19", - "gmt_modified": "2022-01-21 18:04:14", - "advisory_id": "ANBA-2022:0001", - "publish_date": "2022-01-04", - "product": [ - { - "product_id": 7, - "name_version": "Anolis 8.4", - "product_package_info": { - "arm": [ - "11" - ] - } - } - ], - "publisher": "hxk01075255", - "affected_packages": [ - "11" - ], - "advisory_type": "Bug Fix Advisory", - "severity": "Important", - "is_publish": true, - "synpopsis": "11", - "description": "11", - "solution": "11", - "issue": "11", - "source": "manual", - "cve": [] - }, - { - "id": 6, - "gmt_created": "2021-12-30 15:21:54", - "gmt_modified": "2021-12-30 15:52:40", - "advisory_id": "ANBA-2021:0006", - "publish_date": "2021-12-23", - "product": [ - { - "product_id": 7, - "name_version": "Anolis 8.4", - "product_package_info": { - "arm": [ - "rh-maven36-log4j12-1.2.17-23.3.el7.src.rpm\t" - ], - "x86": [ - "rh-maven36-log4j12-1.2.17-23.3.el7.src.rpm\t" - ] - } - }, - { - "product_id": 8, - "name_version": "anolis 10.3.5", - "product_package_info": { - "arm": [ - "rh-maven36-log4j12-javadoc-1.2.17-23.3.el7.noarch.rpm\t", - "rh-maven36-log4j12-javadoc-1.2.17-23.3.el7.noarch.rpm" - ], - "x86": [ - "rh-maven36-log4j12-1.2.17-23.3.el7.src.rpm\t", - "rh-maven36-log4j12-1.2.17-23.3.el7.src.rpm" - ] - } - }, - { - "product_id": 9, - "name_version": "Anolis 8.2", - "product_package_info": { - "arm": [ - "rh-maven36-log4j12-1.2.17-23.3.el7.src.rpm\t" - ], - "x86": [ - "rh-maven36-log4j12-1.2.17-23.3.el7.src.rpm\t" - ] - } - } - ], - "publisher": "wb-cy860729", - "affected_packages": [ - "rh-maven36-log4j12", - "rh-maven36-log4j12-javadoc" - ], - "advisory_type": "Bug Fix Advisory", - "severity": "Critical", - "is_publish": true, - "synpopsis": "An update for rh-maven36-log4j12 is now available for Red Hat Software Collections.\n\nRed Hat Product Security has rated this update as having a security impact of Moderate. A Common Vulnerability Scoring System (CVSS) base score, which gives a detailed severity rating, is available for each vulnerability from the CVE link(s) in the References section.An update for rh-maven36-log4j12 is now available for Red Hat Software Collections.\n\nRed Hat Product Security has rated this update as having a security impact of Moderate. A Common Vulnerability Scoring System (CVSS) base score, which gives a detailed severity rating, is available for each vulnerability from the CVE link(s) in the References section.", - "description": "Red Hat Product Security has rated this update as having a security impact of Moderate. A Common Vulnerability Scoring System (CVSS) base score, which gives a detailed severity rating, is available for each vulnerability from the CVE link(s) in the References section.An update for rh-maven36-log4j12 is now available for Red Hat Software Collections.Red Hat Product Security has rated this update as having a security impact of Moderate. A Common Vulnerability Scoring System (CVSS) base score, which gives a detailed severity rating, is available for each vulnerability from the CVE link(s) in the References section.An update for rh-maven36-log4j12 is now available for Red Hat Software Collections.Red Hat Product Security has rated this update as having a security impact of Moderate. A Common Vulnerability Scoring System (CVSS) base score, which gives a detailed severity rating, is available for each vulnerability from the CVE link(s) in the References section.An update for rh-maven36-log4j12 is now available for Red Hat Software Collections.Red Hat Product Security has rated this update as having a security impact of Moderate. A Common Vulnerability Scoring System (CVSS) base score, which gives a detailed severity rating, is available for each vulnerability from the CVE link(s) in the References section.An update for rh-maven36-log4j12 is now available for Red Hat Software Collections.Red Hat Product Security has rated this update as having a security impact of Moderate. A Common Vulnerability Scoring System (CVSS) base score, which gives a detailed severity rating, is available for each vulnerability from the CVE link(s) in the References section.An update for rh-maven36-log4j12 is now available for Red Hat Software Collections.Red Hat Product Security has rated this update as having a security impact of Moderate. A Common Vulnerability Scoring System (CVSS) base score, which gives a detailed severity rating, is available for each vulnerability from the CVE link(s) in the References section.An update for rh-maven36-log4j12 is now available for Red Hat Software Collections.", - "solution": "An update for rh-maven36-log4j12 is now available for Red Hat Software Collections.\n\nRed Hat Product Security has rated this update as having a security impact of Moderate. A Common Vulnerability Scoring System (CVSS) base score, which gives a detailed severity rating, is available for each vulnerability from the CVE link(s) in the References section.", - "issue": "An update for rh-maven36-log4j12 is now available for Red Hat Software Collections.\n\nRed Hat Product Security has rated this update as having a security impact of Moderate. A Common Vulnerability Scoring System (CVSS) base score, which gives a detailed severity rating, is available for each vulnerability from the CVE link(s) in the References section.\n\n\nhttps://access.redhat.com/articles/11258", - "source": "manual", - "cve": [] - }, - { - "id": 3, - "gmt_created": "2021-12-29 09:55:25", - "gmt_modified": "2021-12-29 09:55:25", - "advisory_id": "ANEA-2021:0003", - "publish_date": "2021-07-21", - "product": [ - { - "product_id": 6, - "name_version": "Anolis 8.2", - "product_package_info": { - "arm": [ - "nodejs-14.17.5-1.module+an8.4.0+10386+02ee7ad9.aarch64.rpm", - "nodejs-14.17.1-1.module+an8.4.0+10386+02ee7ad9.aarch64.rpm" - ] - } - }, - { - "product_id": 7, - "name_version": "Anolis 8.4", - "product_package_info": { - "arm": [ - "nodejs-14.17.5-1.module+an8.4.0+10386+02ee7ad9.aarch64.rpm", - "nodejs-14.17.1-1.module+an8.4.0+10386+02ee7ad9.aarch64.rpm" - ], - "x86": [ - "nodejs-14.17.5-1.module+an8.4.0+10386+02ee7ad9.aarch64.rpm", - "nodejs-14.17.1-1.module+an8.4.0+10386+02ee7ad9.aarch64.rpm" - ] - } - } - ], - "publisher": "wb-cy860729", - "affected_packages": [ - "nodejs" - ], - "advisory_type": "Enhancement Advisory", - "severity": "Critical", - "is_publish": true, - "synpopsis": "synpopsis", - "description": "description", - "solution": "solution", - "issue": "issue", - "source": "manual", - "cve": [] - }, - { - "id": 2, - "gmt_created": "2021-12-28 19:13:15", - "gmt_modified": "2021-12-28 19:13:15", - "advisory_id": "ANEA-2021:0002", - "publish_date": "2021-07-21", - "product": [ - { - "product_id": 6, - "name_version": "Anolis 8.2", - "product_package_info": { - "arm": [ - "nodejs-14.17.5-1.module+an8.4.0+10386+02ee7ad9.aarch64.rpm", - "nodejs-14.17.1-1.module+an8.4.0+10386+02ee7ad9.aarch64.rpm" - ] - } - }, - { - "product_id": 7, - "name_version": "Anolis 8.4", - "product_package_info": { - "arm": [ - "nodejs-14.17.5-1.module+an8.4.0+10386+02ee7ad9.aarch64.rpm", - "nodejs-14.17.1-1.module+an8.4.0+10386+02ee7ad9.aarch64.rpm" - ], - "x86": [ - "nodejs-14.17.5-1.module+an8.4.0+10386+02ee7ad9.aarch64.rpm", - "nodejs-14.17.1-1.module+an8.4.0+10386+02ee7ad9.aarch64.rpm" - ] - } - } - ], - "publisher": "wb-cy860729", - "affected_packages": [ - "nodejs" - ], - "advisory_type": "Enhancement Advisory", - "severity": "Critical", - "is_publish": true, - "synpopsis": "synpopsis", - "description": "description", - "solution": "solution", - "issue": "issue", - "source": "manual", - "cve": [] - }, - { - "id": 1, - "gmt_created": "2021-12-28 19:06:48", - "gmt_modified": "2021-12-29 18:34:22", - "advisory_id": "ANEA-2021:0001", - "publish_date": "2021-07-21", - "product": [ - { - "product_id": 7, - "name_version": "Anolis 8.4", - "product_package_info": { - "arm": [ - "nodejs-14.17.5-1.module+an8.4.0+10386+02ee7ad9.aarch64.rpm", - "nodejs-14.17.1-1.module+an8.4.0+10386+02ee7ad9.aarch64.rpm" - ] - } - }, - { - "product_id": 9, - "name_version": "Anolis 8.2", - "product_package_info": { - "arm": [ - "nodejs-14.17.5-1.module+an8.4.0+10386+02ee7ad9.aarch64.rpm", - "nodejs-14.17.1-1.module+an8.4.0+10386+02ee7ad9.aarch64.rpm" - ], - "x86": [ - "nodejs-14.17.5-1.module+an8.4.0+10386+02ee7ad9.aarch64.rpm", - "nodejs-14.17.1-1.module+an8.4.0+10386+02ee7ad9.aarch64.rpm" - ] - } - } - ], - "publisher": "wb-cy860729", - "affected_packages": [ - "nodejs" - ], - "advisory_type": "Enhancement Advisory", - "severity": "Critical", - "is_publish": true, - "synpopsis": "synpopsis", - "description": "description", - "solution": "solution", - "issue": "issue", - "source": "manual", - "cve": [] - } - ] -} -``` - -## Errata接口 - -### 1) Errata列表 - -> 获取Errata列表 -url: /api/v1/errata/ -请求方式: GET -支持格式: application/json - - -**请求参数** - -| 参数 | 必选 | 类型 | 说明 | -| --- | --- | --- | --- | -| page_num | 否 | int | 当前页 | -| page_size | 否 | int | 每页条数20-100 | - - -**返回字段** - -| 返回字段 | 字段类型 | 说明 | -| --- | --- | --- | -| total | int | 总条数 | -| page_num | int | 当前页 | -| total_page | int | 总页数 | -| page_size | int | 每页条数 | -| previous | string | 上一页 | -| next | string | 下一页 | -| data | list | 列表数据 | -| id | int | | -| gmt_created | date | 创建时间 | -| gmt_modified | date | 更新时间 | -| advisory_id | str | advisory ID | -| advisory_type | str | advisory类型 | -| severity | 否 | str | -| is_publish | bool | 是否发布 | -| publisher | str | 发布人 | -| synpopsis | str | 简介 | -| solution | str | 描述 | -| description | str | 解决方案 | -| issue | str | Issue | -| source | str | 来源，值为manual(手动)或者添加者的(sys_name) | -| cve | list | 关联的cve | -| affected_packages | list | 受影响的包 | -| product | list | 关联的产品和package信息 | -| modules | list | errata修复的modules信息 | - - -**接口示例** - -> 地址：/api/v1/errata/?page_num=1&page_size=20 - - -```json -{ - "total": 4, // 总个数 - "page_num": 1, // 当前页 - "total_page": 1, // 总页数 - "page_size": 20, // 每页条数 - "previous": null, // 上一页url - "next": null, // 下一页url - "data": [ - { - "id": 6, - "gmt_created": "2021-12-30 15:21:54", // 创建时间 - "gmt_modified": "2021-12-30 15:52:40", // 更新时间 - "advisory_id": "ANBA-2021:0006", // advisory ID - "publish_date": "2021-12-23", // 发布时间 - "product": [ // 关联的产品和package信息 - { - "product_id": 7, // 产品id - "name_version": "Anolis 8.4", // 产品名称及版本 - "product_package_info": { // package信息 - "arm": [ // 架构 - "rh-maven36-log4j12-1.2.17-23.3.el7.src.rpm" // 包名 - ], - "x86": [ - "rh-maven36-log4j12-1.2.17-23.3.el7.src.rpm" - ] - } - } - ], - "publisher": "wb-cy860729", // 发布人 - "affected_packages": [ // 受影响的包 - "rh-maven36-log4j12", - "rh-maven36-log4j12-javadoc" - ], - "advisory_type": "Bug Fix Advisory", // advisory类型 - "severity": "Critical", // 严重级别 - "is_publish": true, // 是否发布 - "synpopsis": "An update for rh-maven36-log4j12 is now available for Red Hat Software Collections.\n\nRed Hat Product Security has rated this update as having a security impact of Moderate. A Common Vulnerability Scoring System (CVSS) base score, which gives a detailed severity rating, is available for each vulnerability from the CVE link(s) in the References section.An update for rh-maven36-log4j12 is now available for Red Hat Software Collections.\n\nRed Hat Product Security has rated this update as having a security impact of Moderate. A Common Vulnerability Scoring System (CVSS) base score, which gives a detailed severity rating, is available for each vulnerability from the CVE link(s) in the References section.", - // 简介 - "description": "Red Hat Product Security has rated this update as having a security impact of Moderate. A Common Vulnerability Scoring System (CVSS) base score, which gives a detailed severity rating, is available for each vulnerability from the CVE link(s) in the References section.An update for rh-maven36-log4j12 is now available for Red Hat Software Collections.Red Hat Product Security has rated this update as having a security impact of Moderate. A Common Vulnerability Scoring System (CVSS) base score, which gives a detailed severity rating, is available for each vulnerability from the CVE link(s) in the References section.An update for rh-maven36-log4j12 is now available for Red Hat Software Collections.Red Hat Product Security has rated this update as having a security impact of Moderate. A Common Vulnerability Scoring System (CVSS) base score, which gives a detailed severity rating, is available for each vulnerability from the CVE link(s) in the References section.An update for rh-maven36-log4j12 is now available for Red Hat Software Collections.Red Hat Product Security has rated this update as having a security impact of Moderate. A Common Vulnerability Scoring System (CVSS) base score, which gives a detailed severity rating, is available for each vulnerability from the CVE link(s) in the References section.An update for rh-maven36-log4j12 is now available for Red Hat Software Collections.Red Hat Product Security has rated this update as having a security impact of Moderate. A Common Vulnerability Scoring System (CVSS) base score, which gives a detailed severity rating, is available for each vulnerability from the CVE link(s) in the References section.An update for rh-maven36-log4j12 is now available for Red Hat Software Collections.Red Hat Product Security has rated this update as having a security impact of Moderate. A Common Vulnerability Scoring System (CVSS) base score, which gives a detailed severity rating, is available for each vulnerability from the CVE link(s) in the References section.An update for rh-maven36-log4j12 is now available for Red Hat Software Collections.", - // 描述 - "solution": "An update for rh-maven36-log4j12 is now available for Red Hat Software Collections.\n\nRed Hat Product Security has rated this update as having a security impact of Moderate. A Common Vulnerability Scoring System (CVSS) base score, which gives a detailed severity rating, is available for each vulnerability from the CVE link(s) in the References section.", - // 解决方案 - "issue": "An update for rh-maven36-log4j12 is now available for Red Hat Software Collections.\n\nRed Hat Product Security has rated this update as having a security impact of Moderate. A Common Vulnerability Scoring System (CVSS) base score, which gives a detailed severity rating, is available for each vulnerability from the CVE link(s) in the References section.\n\n\nhttps://access.redhat.com/articles/11258", - // Issue - "source": "manual", // 来源 - "cve": [] // 关联的cve - }, - { - "id": 3, - "gmt_created": "2021-12-29 09:55:25", - "gmt_modified": "2021-12-29 09:55:25", - "advisory_id": "ANEA-2021:0003", - "publish_date": "2021-07-21", - "product": [ - { - "product_id": 6, - "name_version": "Anolis 8.2", - "product_package_info": { - "arm": [ - "nodejs-14.17.5-1.module+an8.4.0+10386+02ee7ad9.aarch64.rpm", - "nodejs-14.17.1-1.module+an8.4.0+10386+02ee7ad9.aarch64.rpm" - ] - } - }, - { - "product_id": 7, - "name_version": "Anolis 8.4", - "product_package_info": { - "arm": [ - "nodejs-14.17.5-1.module+an8.4.0+10386+02ee7ad9.aarch64.rpm", - "nodejs-14.17.1-1.module+an8.4.0+10386+02ee7ad9.aarch64.rpm" - ], - "x86": [ - "nodejs-14.17.5-1.module+an8.4.0+10386+02ee7ad9.aarch64.rpm", - "nodejs-14.17.1-1.module+an8.4.0+10386+02ee7ad9.aarch64.rpm" - ] - } - } - ], - "publisher": "wb-cy860729", - "affected_packages": [ - "nodejs" - ], - "advisory_type": "Enhancement Advisory", - "severity": "Critical", - "is_publish": true, - "synpopsis": "synpopsis", - "description": "description", - "solution": "solution", - "issue": "issue", - "source": "manual", - "cve": [] - }, - { - "id": 2, - "gmt_created": "2021-12-28 19:13:15", - "gmt_modified": "2021-12-28 19:13:15", - "advisory_id": "ANEA-2021:0002", - "publish_date": "2021-07-21", - "product": [ - { - "product_id": 6, - "name_version": "Anolis 8.2", - "product_package_info": { - "arm": [ - "nodejs-14.17.5-1.module+an8.4.0+10386+02ee7ad9.aarch64.rpm", - "nodejs-14.17.1-1.module+an8.4.0+10386+02ee7ad9.aarch64.rpm" - ] - } - }, - { - "product_id": 7, - "name_version": "Anolis 8.4", - "product_package_info": { - "arm": [ - "nodejs-14.17.5-1.module+an8.4.0+10386+02ee7ad9.aarch64.rpm", - "nodejs-14.17.1-1.module+an8.4.0+10386+02ee7ad9.aarch64.rpm" - ], - "x86": [ - "nodejs-14.17.5-1.module+an8.4.0+10386+02ee7ad9.aarch64.rpm", - "nodejs-14.17.1-1.module+an8.4.0+10386+02ee7ad9.aarch64.rpm" - ] - } - } - ], - "publisher": "wb-cy860729", - "affected_packages": [ - "nodejs" - ], - "advisory_type": "Enhancement Advisory", - "severity": "Critical", - "is_publish": true, - "synpopsis": "synpopsis", - "description": "description", - "solution": "solution", - "issue": "issue", - "source": "manual", - "cve": [] - }, - { - "id": 1, - "gmt_created": "2021-12-28 19:06:48", - "gmt_modified": "2021-12-29 18:34:22", - "advisory_id": "ANEA-2021:0001", - "publish_date": "2021-07-21", - "product": [ - { - "product_id": 7, - "name_version": "Anolis 8.4", - "product_package_info": { - "arm": [ - "nodejs-14.17.5-1.module+an8.4.0+10386+02ee7ad9.aarch64.rpm", - "nodejs-14.17.1-1.module+an8.4.0+10386+02ee7ad9.aarch64.rpm" - ] - } - }, - { - "product_id": 9, - "name_version": "Anolis 8.2", - "product_package_info": { - "arm": [ - "nodejs-14.17.5-1.module+an8.4.0+10386+02ee7ad9.aarch64.rpm", - "nodejs-14.17.1-1.module+an8.4.0+10386+02ee7ad9.aarch64.rpm" - ], - "x86": [ - "nodejs-14.17.5-1.module+an8.4.0+10386+02ee7ad9.aarch64.rpm", - "nodejs-14.17.1-1.module+an8.4.0+10386+02ee7ad9.aarch64.rpm" - ] - } - } - ], - "publisher": "wb-cy860729", - "affected_packages": [ - "nodejs" - ], - "advisory_type": "Enhancement Advisory", - "severity": "Critical", - "is_publish": true, - "synpopsis": "synpopsis", - "description": "description", - "solution": "solution", - "issue": "issue", - "source": "manual", - "cve": [], - "modules": ["container-tools:an8", "container-tools:an7"] - } - ] -} -``` - -### 2). 添加 - -> 功能描述: 添加 errata -url: /api/v1/errata/ -请求方式: POST -支持格式: application/json - - -**请求参数** - -| 参数 | 必选 | 类型 | 说明 | -| --- | --- | --- | --- | -| advisory_id | 否 | str | errata官方公告id, 唯一性，如：ANEA-2022:0027 | -| advisory_type | 是 | str | advisory类型, 只能是下面三种之一 Enhancement Advisory, Bug Fix Advisory, Security Advisory | -| severity | 否 | str | ANSA的严重等级, 只能是下面四种之一 Critical, Important, Moderate, Low,ANBA/ANEA下无严重等级 | -| is_publish | 否 | bool | 是否发布，默认false | -| publish_date | 是 | str | 发布时间 格式"Y-m-d" 2021-07-21 | -| synpopsis | 是 | str | 简介 | -| description | 是 | str | 描述 | -| solution | 是 | str | 解决方案 | -| issue | 否 | str | Issue | -| cve | 否 | list | 关联的cve, 如`["CVE-2021-45257", "CVE-2021-45258"]` -,CVE id必须已存在 | -| product | 是 | list | 关联的product，一个errata只能关联一个产品，没有给空列表[] | -| modules | 否 | list | errata修复的modules信息，若是package，该字段无需填写；若是module，该字段填写module名及版本，如：ruby:2.5 | - - -**接口示例** - -> 方式：POST -地址：/api/v1/errata/ -参数： - - -```json -{ - "advisory_id": "ANEA-2022:0028", // 非必填， errata官方公告id，唯一 - "advisory_type": "Enhancement Advisory", // 必填， advisory类型, 只能是下面三种之一 Enhancement Advisory, Bug Fix Advisory, Security Advisory - "severity": "Critical", // 必填，严重等级, 只能是下面四种之一 Critical, Important, Medium, Low - "publish_date": "2021-07-21", // 必填，发布时间 格式"Y-m-d" 2021-07-21 - "synpopsis": "synpopsis", // 必填， - "description": "description", // 必填， - "solution": "solution", // 必填， - "issue": "issue", // 必填， - "is_publish": true, // 选填，不填默认不发布，如需添加即发布，请设为true - "cve": [ - "CVE-2020-12131", - "CVE-2020-12132" - ], // 关联的cve, CVE id必须已存在 - "modules": ["ruby:2.5", "ruby:2.6"], // errata修复的modules信息, 若是no-module，该字段无需填写 - "product": [ - { - "name_version": "Anolis8.2", // name_version必填，name_version必须存在 - "product_package_info": { // 必填 - "aarch64": [ // 架构必须在['aarch64', 'x86_64', 'src', 'noarch']之中 - { - "rpm_filename": "nodejs-14.17.5-1.module+an8.4.0+10386+02ee7ad9.aarch64.rpm", // 文件名称 - "rpm_name": "nodejs", // 包名称 - "rpm_url": "http://mirrors.openanolis.cn/anolis/8.4/AppStream/aarch64/os/Packages/nodejs-14.17.5-1.module+an8.4.0+10386+02ee7ad9.aarch64.rpm" // 软件包下载URL - } - ] // "aarch64"、"x86_64"、"src"、"noarch"至少有一个，并且包名不能为空，包名长度、文件名称长度不能超过128 - , - "x86_64": [ - { - "rpm_filename": "nodejs-14.17.5-1.module+an8.4.0+10386+02ee7ad9.aarch64.rpm", - "rpm_name": "nodejs", - "rpm_url": "http://mirrors.openanolis.cn/anolis/8.4/AppStream/aarch64/os/Packages/nodejs-14.17.5-1.module+an8.4.0+10386+02ee7ad9.aarch64.rpm" - }, - { - "rpm_filename": "nodejs-14.17.5-1.module+an8.4.0+10386+02ee7ad9.aarch64.rpm", - "rpm_name": "nodejs", - "rpm_url": "http://mirrors.openanolis.cn/anolis/8.4/AppStream/aarch64/os/Packages/nodejs-14.17.5-1.module+an8.4.0+10386+02ee7ad9.aarch64.rpm" - } - ] - , - "loongarch64": [ - { - "rpm_filename": "nodejs-14.17.5-1.module+an8.4.0+10386+02ee7ad9.aarch64.rpm", - "rpm_name": "nodejs", - "rpm_url": "http://mirrors.openanolis.cn/anolis/8.4/AppStream/aarch64/os/Packages/nodejs-14.17.5-1.module+an8.4.0+10386+02ee7ad9.aarch64.rpm" - }, - { - "rpm_filename": "nodejs-14.17.5-1.module+an8.4.0+10386+02ee7ad9.aarch64.rpm", - "rpm_name": "nodejs", - "rpm_url": "http://mirrors.openanolis.cn/anolis/8.4/AppStream/aarch64/os/Packages/nodejs-14.17.5-1.module+an8.4.0+10386+02ee7ad9.aarch64.rpm" - } - ] - } - }, - { - "name_version": "Anolis8.4", - "product_package_info": { - "aarch64": [ - { - "rpm_filename": "nodejs-14.17.5-1.module+an8.4.0+10386+02ee7ad9.aarch64.rpm", - "rpm_name": "nodejs", - "rpm_url": "http://mirrors.openanolis.cn/anolis/8.4/AppStream/aarch64/os/Packages/nodejs-14.17.5-1.module+an8.4.0+10386+02ee7ad9.aarch64.rpm" - } - ], - "x86_64": [ - { - "rpm_filename": "nodejs-14.17.5-1.module+an8.4.0+10386+02ee7ad9.aarch64.rpm", - "rpm_name": "nodejs", - "rpm_url": "http://mirrors.openanolis.cn/anolis/8.4/AppStream/aarch64/os/Packages/nodejs-14.17.5-1.module+an8.4.0+10386+02ee7ad9.aarch64.rpm" - }, - { - "rpm_filename": "nodejs-14.17.5-1.module+an8.4.0+10386+02ee7ad9.aarch64.rpm", - "rpm_name": "nodejs", - "rpm_url": "http://mirrors.openanolis.cn/anolis/8.4/AppStream/aarch64/os/Packages/nodejs-14.17.5-1.module+an8.4.0+10386+02ee7ad9.aarch64.rpm" - } - ] - } - } - ] -} -``` - -成功返回： - -```json -{ - "status": { - "code": 201, - "message": "" - }, - "data": { - "id": 40, - "gmt_created": "2022-02-09 17:16:22", - "gmt_modified": "2022-02-09 17:16:22", - "advisory_id": "ANEA-2022:0028", - "publish_date": "2021-07-21", - "modules": ["ruby:2.5", "ruby:2.6"], - "product": [ - { - "product_id": 2, - "name_version": "Anolis8.2", - "product_package_info": { - "aarch64": [ - { - "rpm_filename": "nodejs-14.17.5-1.module+an8.4.0+10386+02ee7ad9.aarch64.rpm", - "rpm_name": "nodejs", - "rpm_url": "http://mirrors.openanolis.cn/anolis/8.4/AppStream/aarch64/os/Packages/nodejs-14.17.5-1.module+an8.4.0+10386+02ee7ad9.aarch64.rpm" - } - ], - "x86_64": [ - { - "rpm_filename": "nodejs-14.17.5-1.module+an8.4.0+10386+02ee7ad9.aarch64.rpm", - "rpm_name": "nodejs", - "rpm_url": "http://mirrors.openanolis.cn/anolis/8.4/AppStream/aarch64/os/Packages/nodejs-14.17.5-1.module+an8.4.0+10386+02ee7ad9.aarch64.rpm" - }, - { - "rpm_filename": "nodejs-14.17.5-1.module+an8.4.0+10386+02ee7ad9.aarch64.rpm", - "rpm_name": "nodejs", - "rpm_url": "http://mirrors.openanolis.cn/anolis/8.4/AppStream/aarch64/os/Packages/nodejs-14.17.5-1.module+an8.4.0+10386+02ee7ad9.aarch64.rpm" - } - ] - , - "loongarch64": [ - { - "rpm_filename": "nodejs-14.17.5-1.module+an8.4.0+10386+02ee7ad9.aarch64.rpm", - "rpm_name": "nodejs", - "rpm_url": "http://mirrors.openanolis.cn/anolis/8.4/AppStream/aarch64/os/Packages/nodejs-14.17.5-1.module+an8.4.0+10386+02ee7ad9.aarch64.rpm" - }, - { - "rpm_filename": "nodejs-14.17.5-1.module+an8.4.0+10386+02ee7ad9.aarch64.rpm", - "rpm_name": "nodejs", - "rpm_url": "http://mirrors.openanolis.cn/anolis/8.4/AppStream/aarch64/os/Packages/nodejs-14.17.5-1.module+an8.4.0+10386+02ee7ad9.aarch64.rpm" - } - ] - } - }, - { - "product_id": 1, - "name_version": "Anolis8.4", - "product_package_info": { - "aarch64": [ - { - "rpm_filename": "nodejs-14.17.5-1.module+an8.4.0+10386+02ee7ad9.aarch64.rpm", - "rpm_name": "nodejs", - "rpm_url": "http://mirrors.openanolis.cn/anolis/8.4/AppStream/aarch64/os/Packages/nodejs-14.17.5-1.module+an8.4.0+10386+02ee7ad9.aarch64.rpm" - } - ], - "x86_64": [ - { - "rpm_filename": "nodejs-14.17.5-1.module+an8.4.0+10386+02ee7ad9.aarch64.rpm", - "rpm_name": "nodejs", - "rpm_url": "http://mirrors.openanolis.cn/anolis/8.4/AppStream/aarch64/os/Packages/nodejs-14.17.5-1.module+an8.4.0+10386+02ee7ad9.aarch64.rpm" - }, - { - "rpm_filename": "nodejs-14.17.5-1.module+an8.4.0+10386+02ee7ad9.aarch64.rpm", - "rpm_name": "nodejs", - "rpm_url": "http://mirrors.openanolis.cn/anolis/8.4/AppStream/aarch64/os/Packages/nodejs-14.17.5-1.module+an8.4.0+10386+02ee7ad9.aarch64.rpm" - } - ] - } - } - ], - "publisher": "test", - "affected_packages": [ - "nodejs" - ], - "advisory_type": "Enhancement Advisory", - "severity": "Critical", - "is_publish": true, - "synpopsis": "synpopsis", - "description": "description", - "solution": "solution", - "issue": "issue", - "source": "test", - "cve": [ - { - "id": 1, - "cve_id": "CVE-2020-12131" - }, - { - "id": 2, - "cve_id": "CVE-2020-12132" - } - ] - } -} -``` - -错误返回： - -```json -{ - "status": { - "code": 400, - "message": { - "advisory_id": [ - "advisory_id不能重复" - ], - "product": { - "0": { - "product_package_info": { - "aarch64": { - "0": { - "non_field_errors": [ - "无效数据。期待为字典类型，得到的是 str 。" - ] - } - }, - "x86_64": { - "0": { - "non_field_errors": [ - "无效数据。期待为字典类型，得到的是 str 。" - ] - }, - "1": { - "non_field_errors": [ - "无效数据。期待为字典类型，得到的是 str 。" - ] - } - } - } - }, - "1": { - "product_package_info": { - "x86_64": { - "0": { - "rpm_filename": [ - "不能超过128个字符" - ], - "rpm_url": [ - "输入的URL不合法" - ] - } - } - } - } - }, - "cve": [ - "属性 cve_id 为 123test 的对象不存在。" - ], - "advisory_type": [ - "只能是((1, 'Bug Fix Advisory'), (2, 'Enhancement Advisory'), (3, 'Security Advisory')), 其中之一" - ], - "severity": [ - "“Critical-test” 不是合法选项。" - ] - }, - "redirect_url": null - }, - "data": null -} -``` - -### 3). 详情 - -> 功能描述: 获取errata详情 -URL: /api/v1/errata/{advisory_id}/ -请求方式: GET -支持格式: application/json - - -** 请求参数** - -| 参数 | 必选 | 类型 | 说明 | -| --- | --- | --- | --- | -| advisory_id | 是 | str | | - - -**接口示例** - -> 地址：/api/v1/errata/ANEA-2022:0013/ -返回 - - -```json -{ - "status": { - "code": 204, - "message": "" - }, - "data": null -} -``` - -### 4). 编辑 - -> 功能描述: 编辑 errata -url: /api/v1/errata/{advisory_id}/ -请求方式: PUT -支持格式: application/json - - -**请求参数** - -| 参数 | 必选 | 类型 | 说明 | -| --- | --- | --- | --- | -| advisory_id | 否 | str | errata官方公告id, 唯一性，如：ANEA-2022:0027 | -| advisory_type | 是 | str | advisory类型, 只能是下面三种之一 Enhancement Advisory, Bug Fix Advisory, Security Advisory | -| severity | 是 | str | 严重等级, 只能是下面四种之一 Critical, Important, Medium, Low | -| is_publish | 否 | bool | 是否发布，默认false | -| publish_date | 是 | str | 发布时间 格式"Y-m-d" 2021-07-21 | -| synpopsis | 是 | str | 简介 | -| description | 是 | str | 描述 | -| solution | 是 | str | 解决方案 | -| issue | 是 | str | Issue | -| cve | 否 | list | 关联的cve, 如`["CVE-2021-45257", "CVE-2021-45258"]` -,CVE id必须已存在 | -| product | 是 | list | 关联的product | -| modules | 否 | list | errata修复的modules信息，若是package，该字段无需填写；若是module，该字段填写module名及版本，如：ruby:2.5 | - - -**接口示例** - -> 方式：PUT -地址：/api/v1/errata/ANBA-2022:0026/ -参数： - - -```json -{ - "advisory_id": "ANBA-2022:0026", - "publish_date": "2022-02-09", - "product": [ - { - "product_id": 2, - "name_version": "Anolis8.4", - "product_package_info": { - "aarch64": [ - { - "rpm_name": "curl", - "rpm_filename": "curl-7.61.1-.1.an8_internal.aarch64.rpm", - "rpm_url": "http://build.openanolis.cn/kojifiles/packages/curl/7.61.1/.1.an8_internal/aarch64/curl-7.61.1-.1.an8_internal.aarch64.rpm" - } - ], - "x86_64": [ - { - "rpm_name": "curl", - "rpm_filename": "curl-7.61.1-.1.an8_internal.x86_64.rpm", - "rpm_url": "http://build.openanolis.cn/kojifiles/packages/curl/7.61.1/.1.an8_internal/x86_64/curl-7.61.1-.1.an8_internal.x86_64.rpm" - } - ] - } - } - ], - "publisher": "hxk01075255", - "affected_packages": [ - "curl" - ], - "advisory_type": "Bug Fix Advisory", - "severity": "Critical", - "is_publish": false, - "synpopsis": "aaa", - "description": "bbb", - "solution": "ccc", - "issue": "ddd", - "source": "manual", - "cve": [], - "modules": ["container-tools:an8", "container-tools:an7"] -} -``` - -成功返回： - -```json -{ - "status": { - "code": 200, - "message": "" - }, - "data": { - "id": 57, - "gmt_created": "2022-02-09 18:41:13", - "gmt_modified": "2022-02-09 18:43:42", - "advisory_id": "ANBA-2022:0026", - "publish_date": "2022-02-09", - "product": [ - { - "product_id": 2, - "name_version": "Anolis8.4", - "product_package_info": { - "aarch64": [ - { - "rpm_name": "curl", - "rpm_filename": "curl-7.61.1-.1.an8_internal.aarch64.rpm", - "rpm_url": "http://build.openanolis.cn/kojifiles/packages/curl/7.61.1/.1.an8_internal/aarch64/curl-7.61.1-.1.an8_internal.aarch64.rpm" - } - ], - "x86_64": [ - { - "rpm_name": "curl", - "rpm_filename": "curl-7.61.1-.1.an8_internal.x86_64.rpm", - "rpm_url": "http://build.openanolis.cn/kojifiles/packages/curl/7.61.1/.1.an8_internal/x86_64/curl-7.61.1-.1.an8_internal.x86_64.rpm" - } - ] - } - } - ], - "publisher": "hxk01075255", - "affected_packages": [ - "curl" - ], - "advisory_type": "Bug Fix Advisory", - "severity": "Critical", - "is_publish": false, - "synpopsis": "aaa", - "description": "bbb", - "solution": "ccc", - "issue": "ddd", - "source": "manual", - "cve": [], - "modules": ["container-tools:an8", "container-tools:an7"] - } -} -``` - -### 5). 删除 - -> 功能描述: 删除errata详情 -URL: /api/v1/errata/{advisory_id}/ -请求方式: DELETE -支持格式: application/json - - -** 请求参数** - -| 参数 | 必选 | 类型 | 说明 | -| --- | --- | --- | --- | -| advisory_id | 是 | str | | - - -**接口示例** - -> 地址：/api/v1/errata/ANBA-2022:0007/ - - -返回： - -```json -{ - "status": { - "code": 204, - "message": "" - }, - "data": null -} -``` - -## CVE接口 - -### 1) CVE列表 - -> 获取Errata列表 -url: /api/v1/cve/ -请求方式: GET -支持格式: application/json - - -**请求参数** - -| 参数 | 必选 | 类型 | 说明 | -| --- | --- | --- | --- | -| page_num | 否 | int | 当前页 | -| page_size | 否 | int | 每页条数20-100 | - - -**返回字段** - -| 返回字段 | 字段类型 | 说明 | -| --- | --- | --- | -| total | int | 总条数 | -| page_num | int | 当前页 | -| total_page | int | 总页数 | -| page_size | int | 每页条数 | -| previous | string | 上一页 | -| next | string | 下一页 | -| data | list | 列表数据 | -| id | int | | -| gmt_created | date | 创建时间 | -| gmt_modified | date | 更新时间 | -| cve_id | str | CEV的标识ID | -| publisher | str | 发布人 | -| affected_errata | list | 受影响的errata | -| score | float | cvss评分 | -| severity | 是 | string | -| status | int | 是否发布 | -| source | str | cve来源 可选 ['Mitre', 'NVD'] | -| publish_date | date | 发布时间 | -| abstract | str | 概要 | -| description | str | 备注 | -| issue | 否 | string | -| acknowledgements | 否 | string | -| acknowledgements_en | 否 | string | -| reference | 否 | string | -| diagnose | 否 | string | -| statement | 否 | string | -| mitigation | 否 | string | -| creator | str | 系统创建人 | -| cve_source_link | 否 | string | -| publish_third_party_token | str | 关联的第三方发布系统 | -| cvss | json | nvd/cnvd/openanolis 的cvss度量评分公式 | -| product | 是 | json | - - -**接口示例** - -> 地址：/api/v1/cve/?page_num=1&page_size=20 - - -```json -{ - "status": { - "code": 200, - "message": "" - }, - "data": { - "total": 3, - "page_num": 1, - "total_page": 1, - "page_size": 20, - "previous": null, - "next": null, - "data": [ - { - "id": 4, - "gmt_created": "2022-01-24 21:11:40", // 创建时间 - "gmt_modified": "2022-01-24 21:11:40", // 更新时间 - "cve_id": "CVE-2020-12134", // CEV的标识ID - "publisher": "test", // 发布人 - "affected_errata": [], // 受影响的errata - "score": 4.3, // cvss评分 - "severity": "Moderate", // 漏洞等级 - "status": 2, // 是否发布 - "source": "NVD", // cve来源 - "publish_date": "2021-12-21 15:48:22", // 发布时间 - "cvss": { - "nvd_cvss": "CVSS:3.1/AV:A/AC:H/PR:L/UI:R/S:U/C:L/I:L/A:L", - "cnvd_cvss": "CVSS:3.1/AV:A/AC:H/PR:L/UI:R/S:U/C:L/I:L/A:L", - "openanolis_cvss": "CVSS:3.1/AV:A/AC:H/PR:L/UI:R/S:U/C:L/I:L/A:L" - }, // nvd/cnvd/openanolis 的cvss度量评分公式 - // 概要 - "abstract": "A flaw was discovered in processing setsockopt IPT_SO_SET_REPLACE (or IP6T_SO_SET_REPLACE) for 32 bit processes on 64 bit systems. This flaw will allow local user to gain privileges or cause a DoS through user name space. This action is usually restricted to root-privileged users but can also be leveraged if the kernel is compiled with CONFIG_USER_NS and CONFIG_NET_NS and the user is granted elevated privileges.", - // 说明 - "description": "A flaw was discovered in processing setsockopt IPT_SO_SET_REPLACE (or IP6T_SO_SET_REPLACE) for 32 bit processes on 64 bit systems. This flaw will allow local user to gain privileges or cause a DoS through user name space.", - "creator": null, // 系统创建人 - "publish_third_party_token": "test" // 关联的第三方发布系统 - }, - { - "id": 3, - "gmt_created": "2022-01-24 21:11:35", - "gmt_modified": "2022-01-24 21:11:35", - "cve_id": "CVE-2020-12133", - "publisher": "test", - "affected_errata": [], - "score": 4.3, - "severity": "Moderate", - "status": 2, - "source": "RHEL", - "publish_date": "2021-12-21 15:48:22", - "cvss": { - "nvd_cvss": "CVSS:3.1/AV:A/AC:H/PR:L/UI:R/S:U/C:L/I:L/A:L", - "cnvd_cvss": "CVSS:3.1/AV:A/AC:H/PR:L/UI:R/S:U/C:L/I:L/A:L", - "openanolis_cvss": "CVSS:3.1/AV:A/AC:H/PR:L/UI:R/S:U/C:L/I:L/A:L" - }, - "abstract": "A flaw was discovered in processing setsockopt IPT_SO_SET_REPLACE (or IP6T_SO_SET_REPLACE) for 32 bit processes on 64 bit systems. This flaw will allow local user to gain privileges or cause a DoS through user name space. This action is usually restricted to root-privileged users but can also be leveraged if the kernel is compiled with CONFIG_USER_NS and CONFIG_NET_NS and the user is granted elevated privileges.", - "description": "A flaw was discovered in processing setsockopt IPT_SO_SET_REPLACE (or IP6T_SO_SET_REPLACE) for 32 bit processes on 64 bit systems. This flaw will allow local user to gain privileges or cause a DoS through user name space.", - "creator": null, - "publish_third_party_token": 1 - }, - { - "id": 2, - "gmt_created": "2022-01-24 21:05:10", - "gmt_modified": "2022-01-24 21:05:10", - "cve_id": "CVE-2020-12132", - "publisher": "test", - "affected_errata": [], - "score": 4.3, - "severity": "Moderate", - "status": 2, - "source": "NVD", - "publish_date": "2021-12-21 15:48:22", - "cvss": { - "nvd_cvss": "CVSS:3.1/AV:A/AC:H/PR:L/UI:R/S:U/C:L/I:L/A:L", - "cnvd_cvss": "CVSS:3.1/AV:A/AC:H/PR:L/UI:R/S:U/C:L/I:L/A:L", - "openanolis_cvss": "CVSS:3.1/AV:A/AC:H/PR:L/UI:R/S:U/C:L/I:L/A:L" - }, - "abstract": "A flaw was discovered in processing setsockopt IPT_SO_SET_REPLACE (or IP6T_SO_SET_REPLACE) for 32 bit processes on 64 bit systems. This flaw will allow local user to gain privileges or cause a DoS through user name space. This action is usually restricted to root-privileged users but can also be leveraged if the kernel is compiled with CONFIG_USER_NS and CONFIG_NET_NS and the user is granted elevated privileges.", - "description": "A flaw was discovered in processing setsockopt IPT_SO_SET_REPLACE (or IP6T_SO_SET_REPLACE) for 32 bit processes on 64 bit systems. This flaw will allow local user to gain privileges or cause a DoS through user name space.", - "creator": null, - "publish_third_party_token": "test" - } - ] - } -} -``` - -### 2). 添加 - -> 功能描述: 添加 cve -url: /api/v1/cve/ -请求方式: POST -支持格式: application/json - - -**请求参数** - -| 参数 | 必选 | 类型 | 说明 | -| --- | --- | --- | --- | -| cve_id | 是 | string | cve 编号 | -| score | 是 | float | cvss评分分值 | -| severity | 是 | string | 漏洞等级，可选['Critical', 'Important', 'Low', 'None', 'Moderate',] | -| source | str | cve来源 可选 ['Mitre', 'NVD'] | | -| publish_date | 否 | string | 发布日期 格式"2021-12-21 15:48:22" | -| abstract | 否 | string | 概要 | -| description | 否 | string | 备注 | -| issue | 否 | string | issue | -| acknowledgements | 否 | string | 致谢 | -| acknowledgements_en | 否 | string | 英文致谢 | -| reference | 否 | string | 自定义参考链接 | -| diagnose | 否 | string | cve diagnose脚本 | -| statement | 否 | string | 龙蜥声明 | -| mitigation | 否 | string | CVE缓解方案 | -| status | 是 | int | 可选值1、2，status=1表示保存并发布，status=2表示仅保存 | -| cve_source_link | 否 | string | cve源链接 | -| cvss | 否 | json | nvd/openanolis 的cvss度量评分公式 | -| product | 是 | json | cve关联的产品、包、修复状态 ，没有给空列表[] | -| rpm_name | 是 | str | cve关联的软件包名 | -| rpm_status | 是 | str | cve关联包的修复状态，可选项为：fixed、investigation、unaffected、not_fix、out_scope、affected | -| advisory_id | 否 | str | cve下已修复的包/modules关联的errata（用advisory_id关联），只能在系统已有的errata中选择 | - - -**接口示例** - -> 方式：POST -地址：/api/v1/cve/ -参数： - - -```json -{ - "cve_id": "CVE-2022-25636", - "source": "Mitre", - "publish_date": "2022-04-29 11:14:32", - "abstract": "net/netfilter/nf_dup_netdev.c in the Linux kernel 5.4 through 5.6.10 allows local users to gain privileges because of a heap out-of-bounds write. This is related to nf_tables_offload.", - "description": "URL=https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2022-25636 \ncvss3=7.8/CVSS:3.1/AV:L/AC:L/PR:L/UI:N/S:U/C:H/I:H/A:H", - "issue": "Fastento was created by content marketing experts and news engineers who believe in the future of media.", - "acknowledgements": "致谢：Fastento was created by content marketing experts and news engineers who believe in the future of media.", -"acknowledgements_en": "acknowledgements：Fastento was created by content marketing experts and news engineers who believe in the future of media.", - "reference": "自定义参考链接.", - "diagnose": "cve diagnose脚本", - "cve_source_link": "https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2022-25636", - "score": "7.8", - "severity": "Important", - "cvss": { - "nvd_cvss": "CVSS:3.0/AV:L/AC:L/PR:L/UI:N/S:U/C:H/I:H/A:H", - "openanolis_cvss": "CVSS:3.1/AV:L/AC:L/PR:L/UI:N/S:U/C:H/I:H/A:H" - }, - "product": [ - { - "product_id": 12, - "name_version": "Anolis8.2", - "product_package_info": { - "src": [ - { - "rpm_name": "nodejs", - "rpm_status": "fixed", - "advisory_id": "ANSA-2022:0592" - }, - { - "rpm_name": "python", - "rpm_status": "fixed" - } - ] - } - { - "product_id": 13, - "name_version": "Anolis8.5", - "product_package_info": { - "src": [ - { - "rpm_name": "nodejs", - "rpm_status": "fixed", - "advisory_id": "ANSA-2022:0591" - }, - { - "rpm_name": "python", - "rpm_status": "fixed" - } - ] - } - } - ], - "status": 1 -} -``` - -成功返回： - -```json -{ - "status": { - "code": 201, - "message": "" - }, - "data": { - "id": 52, - "gmt_created": "2022-04-29 11:16:37", - "gmt_modified": "2022-04-29", - "cve_id": "CVE-2022-25636", - "creator": "zhuxiao", - "publisher": "zhuxiao", - "publish_third_party_token": null, - "publish_date": "2022-04-29", - "cvss": { - "nvd_cvss": "CVSS:3.0/AV:L/AC:L/PR:L/UI:N/S:U/C:H/I:H/A:H", - "openanolis_cvss": "CVSS:3.1/AV:L/AC:L/PR:L/UI:N/S:U/C:H/I:H/A:H" - }, - "product": [ - { - "product_id": 12, - "name_version": "Anolis8.2", - "product_package_info": { - "aarch64": [ - { - "rpm_name": "python", - "rpm_status": "fixed" - } - ], - "x86_64": [ - { - "rpm_name": "python", - "rpm_status": "fixed" - } - ], - "src": [ - { - "rpm_name": "python", - "rpm_status": "fixed" - }, - { - "rpm_name": "java", - "rpm_status": "unaffected" - } - ], - "noarch": [ - { - "rpm_name": "java", - "rpm_status": "unaffected" - } - ] - } - }, - { - "product_id": 13, - "name_version": "Anolis8.5", - "product_package_info": { - "aarch64": [ - { - "rpm_name": "python", - "rpm_status": "fixed" - } - ], - "x86_64": [ - { - "rpm_name": "python", - "rpm_status": "fixed" - } - ], - "src": [ - { - "rpm_name": "python", - "rpm_status": "fixed" - }, - { - "rpm_name": "java", - "rpm_status": "unaffected" - } - ], - "noarch": [ - { - "rpm_name": "java", - "rpm_status": "unaffected" - } - ] - } - } - ], - "product_package": [ - { - "name_version": "Anolis8.2", - "rpm_name": "python", - "rpm_status": "fixed" - }, - { - "name_version": "Anolis8.2", - "rpm_name": "java", - "rpm_status": "unaffected" - }, - { - "name_version": "Anolis8.5", - "rpm_name": "java", - "rpm_status": "unaffected" - }, - { - "name_version": "Anolis8.5", - "rpm_name": "python", - "rpm_status": "fixed" - } - ], - "affected_packages": [ - "java", - "python" - ], - "score": 7.8, - "severity": "Important", - "status": 1, - "source": "Mitre", - "cve_source_link": "https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2022-25636", - "abstract": "net/netfilter/nf_dup_netdev.c in the Linux kernel 5.4 through 5.6.10 allows local users to gain privileges because of a heap out-of-bounds write. This is related to nf_tables_offload.", - "description": "URL=https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2022-25636 \ncvss3=7.8/CVSS:3.1/AV:L/AC:L/PR:L/UI:N/S:U/C:H/I:H/A:H", - "acknowledgements": "致谢：Fastento was created by content marketing experts and news engineers who believe in the future of media.", - "acknowledgements_en": "acknowledgements：Fastento was created by content marketing experts and news engineers who believe in the future of media.", - "errata": [] - } -} -``` - -错误返回： - -```json -{ - "status": { - "code": 400, - "message": { - "cve_id": [ - "cve 编号不能重复" - ], - "cvss": { - "nvd_cvss": [ - "cvss向量字符串不符合规则，请检查后正确输入" - ], - "cnvd_cvss": [ - "cvss向量字符串不符合规则，请检查后正确输入" - ], - "openanolis_cvss": [ - "cvss向量字符串不符合规则，请检查后正确输入" - ] - } - }, - "redirect_url": null - }, - "data": null -} -``` - -### 3). 详情 - -> 功能描述: 获取cve详情 -URL: /api/v1/cve/{cve_id}/ -请求方式: GET -支持格式: application/json - - -** 请求参数** - -| 参数 | 必选 | 类型 | 说明 | -| --- | --- | --- | --- | -| id | 是 | int | | - - -**接口示例** - -> 地址：/api/v1/cve/CVE-2022-46882/ - - -```json -{ - "status": { - "code": 200, - "message": "" - }, - "data": { - "id": 17649, - "gmt_created": "2022-12-19 11:24:46", - "gmt_modified": "2022-12-19", - "cve_id": "CVE-2022-46882", - "creator": null, - "publisher": "distro-team", - "publish_third_party_token": "distro-team", - "publish_date": "2022-12-17", - "cvss": { - "nvd_cvss": "", - "openanolis_cvss": "CVSS:3.1/AV:N/AC:L/PR:N/UI:R/S:C/C:L/I:L/A:N" - }, - "product": [ - { - "product_id": 5, - "name_version": "Anolis OS 8", - "product_package_info": { - "src": [ - { - "rpm_name": "thunderbird", - "rpm_status": "fixed", - "advisory_id": "ANSA-2022:0829" - }, - { - "rpm_name": "firefox", - "rpm_status": "fixed", - "advisory_id": "ANSA-2022:0830" - } - ] - } - } - ], - "affected_packages": [ - "thunderbird", - "firefox" - ], - "score": 6.1, - "severity": "Moderate", - "product_package": [ - { - "name_version": "Anolis OS 8", - "rpm_name": "thunderbird", - "rpm_status": "fixed", - "advisory_id": "ANSA-2022:0829", - "publish_date": "2022-12-17" - }, - { - "name_version": "Anolis OS 8", - "rpm_name": "firefox", - "rpm_status": "fixed", - "advisory_id": "ANSA-2022:0830", - "publish_date": "2022-12-17" - } - ], - "status": 1, - "source": "Mitre", - "cve_source_link": "", - "abstract": "The Mozilla Foundation Security Advisory describes this flaw as: A use-after-free in WebGL extensions could have led to a potentially exploitable crash.", - "description": null, - "issue": null, - "acknowledgements": "", - "acknowledgements_en": "", - "reference": null, - "diagnose": null, - "statement": null, - "mitigation": null, - "update_user": "distro-team", - "errata": [ - { - "id": 6894, - "advisory_id": "ANSA-2022:0829", - "publish_date": "2022-12-17", - "product_package": { - "name_version": [ - "Anolis OS 8" - ], - "rpm_name": [ - "thunderbird" - ] - } - }, - { - "id": 6895, - "advisory_id": "ANSA-2022:0830", - "publish_date": "2022-12-17", - "product_package": { - "name_version": [ - "Anolis OS 8" - ], - "rpm_name": [ - "firefox" - ] - } - } - ] - } -} -``` - -### 4). 编辑 - -> 功能描述: cve编辑 -URL: /api/v1/cve/{cve_id}/ -请求方式: PUT -支持格式: application/json - - -** 请求参数** - -| 参数 | 必选 | 类型 | 说明 | -| --- | --- | --- | --- | -| cve_id | 是 | string | cve 编号 | -| score | 是 | float | cvss评分分值 | -| severity | 是 | string | 漏洞等级，可选['Critical', 'Important', 'Low', 'None', 'Moderate',] | -| source | str | cve来源 可选 ['Mitre', 'NVD'] | | -| publish_date | 否 | string | 发布日期 格式"2021-12-21 15:48:22" | -| abstract | 否 | string | 概要 | -| description | 否 | string | 备注 | -| issue | 否 | string | issue | -| acknowledgements | 否 | string | 致谢 | -| reference | 否 | string | 自定义参考链接 | -| diagnose | 否 | string | cve diagnose脚本 | -| statement | 否 | string | 龙蜥声明 | -| mitigation | 否 | string | CVE缓解方案 | -| status | 是 | int | 可选值1、2，status=1表示保存并发布，status=2表示仅保存 | -| cve_source_link | 否 | string | cve源链接 | -| cvss | 否 | json | nvd/openanolis 的cvss度量评分公式 | -| product | 是 | json | cve关联的产品、包、修复状态 | -| rpm_name | 是 | str | cve关联的软件包名 | -| rpm_status | 是 | str | cve关联包的修复状态，可选项为：fixed、investigation、unaffected、not_fix、out_scope、affected | -| advisory_id | 否 | str | cve下已修复的包/modules关联的errata（用advisory_id关联），只能在系统已有的errata中选择 | - - -**接口示例** - -> 地址：/api/v1/cve/CVE-2020-12138/ - - -```json -{ - "cve_id": "CVE-2022-25636", - "source": "NVD", - "publish_date": "2022-04-29 11:33:50", - "abstract": "net/netfilter/nf_dup_netdev.c in the Linux kernel 5.4 through 5.6.10 allows local users to gain privileges because of a heap out-of-bounds write. This is related to nf_tables_offload.", - "description": "URL=https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2022-25636 \ncvss3=7.8/CVSS:3.1/AV:L/AC:L/PR:L/UI:N/S:U/C:H/I:H/A:H", - "cve_source_link": "https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2022-25636", - "score": "7.8", - "severity": "Important", - "cvss": { - "nvd_cvss": "CVSS:3.0/AV:L/AC:L/PR:L/UI:N/S:U/C:H/I:H/A:H", - "openanolis_cvss": "CVSS:3.0/AV:L/AC:L/PR:L/UI:N/S:U/C:H/I:H/A:H" - }, - "product": [ - { - "product_id": 12, - "name_version": "Anolis8.2", - "product_package_info": { - "src": [ - { - "rpm_name": "python", - "rpm_status": "fixed", - "advisory_id": "ANSA-2022:0592" - }, - { - "rpm_name": "java", - "rpm_status": "unaffected" - } - ] - } - }, - { - "product_id": 13, - "name_version": "Anolis8.5", - "product_package_info": { - "src": [ - { - "rpm_name": "python", - "rpm_status": "fixed", - "advisory_id": "ANSA-2022:0591" - }, - { - "rpm_name": "java", - "rpm_status": "unaffected" - } - ] - } - ], - "status": 1 -} -``` - -成功返回 - -``` -{ - "status": { - "code": 200, - "message": "" - }, - "data": { - "id": 52, - "gmt_created": "2022-04-29 11:16:37", - "gmt_modified": "2022-04-29", - "cve_id": "CVE-2022-25636", - "creator": "zhuxiao", - "publisher": "zhuxiao", - "publish_third_party_token": null, - "publish_date": "2022-04-29", - "cvss": { - "nvd_cvss": "CVSS:3.0/AV:L/AC:L/PR:L/UI:N/S:U/C:H/I:H/A:H", - "openanolis_cvss": "CVSS:3.0/AV:L/AC:L/PR:L/UI:N/S:U/C:H/I:H/A:H" - }, - "product": [ - { - "product_id": 12, - "name_version": "Anolis8.2", - "product_package_info": { - "src": [ - { - "rpm_name": "python", - "rpm_status": "fixed", - "advisory_id": "ANSA-2022:0592" - }, - { - "rpm_name": "java", - "rpm_status": "unaffected" - } - ] - }, - { - "product_id": 13, - "name_version": "Anolis8.5", - "product_package_info": { - "src": [ - { - "rpm_name": "python", - "rpm_status": "fixed", - "advisory_id": "ANSA-2022:0591" - }, - { - "rpm_name": "java", - "rpm_status": "unaffected" - } - ] - } - } - ], - "product_package": [ - { - "name_version": "Anolis8.2", - "rpm_name": "python", - "rpm_status": "fixed" - }, - { - "name_version": "Anolis8.2", - "rpm_name": "java", - "rpm_status": "unaffected" - }, - { - "name_version": "Anolis8.5", - "rpm_name": "java", - "rpm_status": "unaffected" - }, - { - "name_version": "Anolis8.5", - "rpm_name": "python", - "rpm_status": "fixed" - } - ], - "affected_packages": [ - "java", - "python" - ], - "score": 7.8, - "severity": "Important", - "status": 1, - "source": "NVD", - "cve_source_link": "https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2022-25636", - "abstract": "net/netfilter/nf_dup_netdev.c in the Linux kernel 5.4 through 5.6.10 allows local users to gain privileges because of a heap out-of-bounds write. This is related to nf_tables_offload.", - "description": "URL=https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2022-25636 \ncvss3=7.8/CVSS:3.1/AV:L/AC:L/PR:L/UI:N/S:U/C:H/I:H/A:H", - "errata": [] - } -} -``` - -### 5). 删除 - -> 功能描述: 删除cve -URL: /api/v1/cve/{cve_id}/ -请求方式: DELETE -支持格式: application/json - - -** 请求参数** - -| 参数 | 必选 | 类型 | 说明 | -| --- | --- | --- | --- | -| cve_id | 是 | string | cve 编号 | - - -**接口示例** - -> 地址：/api/v1/cve/CVE-2020-12134/ - - -```json -{ - "status": { - "code": 204, - "message": "" - }, - "data": null -} -``` - -## product查询接口 - -### 1) product列表 - -> 获取产品列表 -url: /api/v1/product/ -请求方式: GET -支持格式: application/json - - -**请求参数** - -| 参数 | 必选 | 类型 | 说明 | -| --- | --- | --- | --- | -| page_num | 否 | int | 当前页 | -| page_size | 否 | int | 每页条数20-100 | - - -**返回字段** - -| 返回字段 | 字段类型 | 说明 | -| --- | --- | --- | -| total | int | 总条数 | -| page_num | int | 当前页 | -| total_page | int | 总页数 | -| page_size | int | 每页条数 | -| previous | string | 上一页 | -| next | string | 下一页 | -| data | list | 列表数据 | -| id | int | 产品在数据库的id | -| gmt_created | date | 创建时间 | -| gmt_modified | date | 更新时间 | -| name_version | str | 产品名称 | -| creator | str | 产品创建者 | - - -**接口示例** - -> 地址：/api/v1/product/?page_num=1&page_size=20 - - -```json -{ - "status": { - "code": 200, - "message": "" - }, - "data": { - "total": 2, - "page_num": 1, - "total_page": 1, - "page_size": 20, - "previous": null, - "next": null, - "data": [ - { - "id": 1, - "gmt_created": "2022-01-25 16:05:38", - "gmt_modified": "2022-01-25 16:05:39", - "name_version": "Anolis8.4", - "creator": "张康" - }, - { - "id": 2, - "gmt_created": "2022-01-25 16:06:13", - "gmt_modified": "2022-01-25 16:06:14", - "name_version": "Anolis8.2", - "creator": "朱潇" - } - ] - } -} -``` - -## 软件包查询接口 - -### 1) 软件包下载链接列表 - -> 通过cve_id列表查询关联包的下载链接 -url: /api/v1/package/ -请求方式: GET -支持格式: application/json - - -**请求参数** - -| 参数 | 必选 | 类型 | 说明 | -| --- | --- | --- | --- | -| cve_id_list | 是 | list | 待查询的cve_id列表，如['CVE-2022-122202', 'CVE-2022-111712'] | - - -**返回字段** - -| 返回字段 | 字段类型 | 说明 | -| --- | --- | --- | -| data | list | 列表数据 | -| rpm_filename | string | 软件包名 | -| rpm_url | string | 软件包下载链接 | - - -**接口示例** - -> 地址：/api/v1/product/?cve_id_list=CVE-2022-122202&cve_id_list=CVE-2022-111712 - - -```json -{ - "status": { - "code": 200, - "message": "" - }, - "data": [ - { - "CVE-2022-122202": [ - { - "rpm_filename": "python", - "rpm_url": "http://mirrors.openanolis.cn/anolis/8.4/AppStream/aarch64/os/Packages/nodejs-14.17.5-1.module+an8.4.0+10386+02ee7ad9.aarch64.rpm" - }, - { - "rpm_filename": "nodejs-14.17.5-1.module+an8.4.0+10386+02ee7ad9.aarch64.rpm", - "rpm_url": "http://mirrors.openanolis.cn/anolis/8.4/AppStream/aarch64/os/Packages/nodejs-14.17.5-1.module+an8.4.0+10386+02ee7ad9.aarch64.rpm" - } - ] - }, - { - "CVE-2022-111712": [ - { - "rpm_filename": "python", - "rpm_url": "http://mirrors.openanolis.cn/anolis/8.4/AppStream/aarch64/os/Packages/nodejs-14.17.5-1.module+an8.4.0+10386+02ee7ad9.aarch64.rpm" - }, - { - "rpm_filename": "nodejs-14.17.5-1.module+an8.4.0+10386+02ee7ad9.aarch64.rpm", - "rpm_url": "http://mirrors.openanolis.cn/anolis/8.4/AppStream/aarch64/os/Packages/nodejs-14.17.5-1.module+an8.4.0+10386+02ee7ad9.aarch64.rpm" - } - ] - } - ] -} -``` diff --git "a/TECHNOLOGY_DOCS/\345\256\211\345\205\250\347\256\241\347\220\206\347\263\273\347\273\237/OpenAnolis\345\256\211\345\205\250\346\225\260\346\215\256API\346\226\207\346\241\243.md" "b/TECHNOLOGY_DOCS/\345\256\211\345\205\250\347\256\241\347\220\206\347\263\273\347\273\237/OpenAnolis\345\256\211\345\205\250\346\225\260\346\215\256API\346\226\207\346\241\243.md" deleted file mode 100644 index 7d774e2dde5dafd3be4ce066d91c8eda55554e1e..0000000000000000000000000000000000000000 --- "a/TECHNOLOGY_DOCS/\345\256\211\345\205\250\347\256\241\347\220\206\347\263\273\347\273\237/OpenAnolis\345\256\211\345\205\250\346\225\260\346\215\256API\346\226\207\346\241\243.md" +++ /dev/null @@ -1,92 +0,0 @@ -ceshishujsuhsuhsushsuhsushsu -## OpenAnolis安全数据API文档1.0 - -欢迎联系龙蜥安全团队邮件列表：ansa-announce@lists.openanolis.cn - -### 1. 简介 - -OpenAnolis安全数据API对外提供了安全数据的访问接口，通过指定的参数查询OpenAnolis社区安全相关数据。目前API支持CVE、OVAL格式的数据访问，其他数据类型敬请期待。 - -安全数据API提供了OpenAnolis社区的安全相关数据和信息，以更好地支持业务需求和指标衡量，如您对安全数据API有任何的疑问，欢迎联系[龙蜥安全团队](https://lists.openanolis.cn/postorius/lists/ansa-announce.lists.openanolis.cn/)，或者在[OpenAnolis Bugzilla](https://bugzilla.openanolis.cn/)向我们提出issue。 - -**`Base URL`** - -> https://anas.openanolis.cn/api/securitydata - -**`数据格式`** - -对外数据接口支持JSON、XML格式的数据，数据格式可以通过访问url的后缀来标识，如.xml、.json。 - -### 2. CVE接口 -#### 2.1 CVE列表 - -**简介** - -列出所有的CVE，以指定的数据格式返回信息 - -**`JSON`** -> GET /cve.json - -**`XML`** -> GET /cve.xml - -#### 2.2 单条CVE -**简介** - -获取一条CVE的信息 -`JSON` - -> GET /cve/.json - -`XML` - -> GET /cve/.xml -3939920022 -**示例** - -/cve/CVE-2022-2795.xml - -#### 2.3 CVE数据格式 -| **参数名称** | **参数说明** | **备注** | **参数类型** | -| --- | --- | --- | --- | -| name | CVE ID | | string | -| threat_severity | 严重等级 | | string | -| public_date | 发布时间 | | datetime | -| bugzilla | bugzilla链接 | | string | -| details | 漏洞细节 | | string | -| description | 漏洞描述 | | string | -| reference | 参考链接 | | string | -| statement | 漏洞声明 | | string | -| diagnose | 漏洞诊断 | | string | -| mitigation | 缓解方案 | | string | -| acknowledgement | 致谢 | | string | -| cvss_score | CVSS评分 | | float | -| cvss_scoring_vector | CVSS向量 | | str | -| source | CVE数据源 | | str | -| csaw | | | | -| package_state | - | | list(product) | -| product | | | | -| product_name | 产品名称 | | string | -| fix_state | 状态 | | string | -| package_name | 软件名称 | | string | -| cpe | cpe | | string | - -### 3. OVAL接口 -#### 3.1 OVAL列表 -**简介** - -返回产品下所有的OVAL数据列表，OVAL数据接口目前仅支持XML格式 - -`XML` -> GET /oval/.xml - -**示例** - -/oval/anolis-7.xml - -/oval/anolis-8.xml - -### 4. OVAL文件下载 -您可以直接访问[Anolis OS 安全漏洞数据中心](https://anas.openanolis.cn/data)浏览并下载最新的以及历史的OVAL文件。 - -Anolis OS安全漏洞数据中心正在不断完善和优化中，如您有宝贵的建议，欢迎您联系龙蜥安全团队：ansa-announce@lists.openanolis.cn。