diff --git a/README-en.md b/README-en.md new file mode 100644 index 0000000000000000000000000000000000000000..197b6763993b289a0b518b44ac6ee253b62c2cd6 --- /dev/null +++ b/README-en.md @@ -0,0 +1,49 @@ +# openEuler DOCS + +### Introduction + +DOCS contains all documents of the openEuler community, including the release notes, OS installation guide, administrator guide, virtualization, container, and A-Tune user guides, and application development guide. + +### Searching for a Document in DOCS + +Open the **docs** folder. The folder contains documents in Chinese (**zh** folder) and English (**en** folder). The English document is used as an example. In the **en** folder, the **docs** folder contains the content of a specific document, and the **menu** folder contains the overview of the document. +Open the **docs** folder. The relationship between guides and folders is as follows: +* **A-Tune**: *A-Tune User Guide* +* **Administrator**: *Administrator Guide* +* **ApplicationDev**: *Application Development Guide* +* **Container**: *Container User Guide* +* **Installation**: *Installation Guide* +* **Quickstart**: *Quick Start* +* **Releasenotes**: *Release Notes* +* **Virtualization**: *Virtualization Application Guide* +* **userguide**: *openEuler Toolset User Guide* +* **StratoVirt**： *StratoVirt User Guide* + + +### Modifying a Document + +When the openEuler version information is updated, the documents herein also need to be updated. Thank you for providing updates. + +### Checking the Relationship Between Versions and Branches +The DOCS contains the following four branches: + +* **master**: development branch, which is the default branch +* **stable-1.0\_Base**: 1.0 Base version branch, which is displayed in **DOCS** > **1.0 BASE** on the [openEuler community website](https://openeuler.org/) +* **stable-20.03\_LTS**: 20.03 LTS version branch, which is displayed in **DOCS** > **20.03 LTS** on the [openEuler community website](https://openeuler.org/) +* **stable-20.09\_LTS**: 20.09 version branch, which is displayed in **DOCS** > **20.09** on the [openEuler community website](https://openeuler.org/) + +### Participating in SIG +Create or reply to an issue: You can discuss an issue by creating or replying to an issue. +Submit a Pull Request (PR): You can participate in SIG by submitting a PR. +Submit comments: You can submit comments on issues or PRs. +We are always pleased to receive PRs from you. + +### Member +#### Maintainer List +- Rudy_Tan (@rudy_tan) +- amyMaYun (@amy_mayun) +- qiaominna(@qiaominna) + +### Contacting Us +E-mails: dev@openeuler.org +IRC: #openeuler-doc \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000000000000000000000000000000000000..145f3ede6be263ec7022e01046a57fdfb61456f3 --- /dev/null +++ b/README.md @@ -0,0 +1,50 @@ +# openEuler 文档 + +### 介绍 + +Docs包含了openEuler社区的所有文档，包括发行说明、操作系统安装，管理员指南，虚拟化和容器的使用指导，A-Tune使用指导，应用开发指导等内容。 +### 如何在Docs中查找文档 + +打开“docs”文件夹，该文件夹包含了中文（“zh”文件夹）和英文（“en”文件夹）两种语言文档，以中文文档举例进行说明。 +在“zh”文件夹中，进入到目录docs/zh/docs/20.09，“docs”文件夹包含了具体文档的内容，“menu”包含了文档的大纲内容。 +打开“docs”文件夹，各手册和文件夹对应关系如下。 +* A-Tune文件夹对应：A-Tune用户指南 +* Adminnistration文件夹对应手册为：管理员指南 +* ApplicationDev文件夹对应手册为：应用开发指南 +* Container文件夹对应手册为：容器用户指南 +* Installation文件夹对应手册为：安装指南 +* Quickstart文件夹对应手册为：快速入门 +* Releasenotes文件夹对应手册为：发行说明 +* Virtualization文件夹对应手册为：虚拟化应用指南 +* userguide文件夹对应手册为：openEuler工具集用户指南 +* StratoVirt文件夹对应手册为：StratoVrit虚拟化用户指南 + + +### 如何修改文档 + +当openEuler版本信息有刷新时，这里文档也需要刷新。很感谢您愿意提供刷新内容。 +请阅读[资料开发流程指导](https://gitee.com/lss410313/docs/wikis/Home)进行操作参考。 + +### 如何查看版本分支对应关系 +Docs当前使用如下4个分支： +* master：开发分支，为默认分支。 +* stable2-1.0_Base：1.0 Base版本分支，分支内容呈现在[openEuler社区](https://openeuler.org/)网站“文档->1.0 BASE。 +* stable2-20.03_LTS：20.03 LTS版本分支，分支内容呈现在[openEuler社区](https://openeuler.org/)网站“文档->20.03 LTS”。 +* stable2-20.09：20.09 版本分支，分支内容呈现在[openEuler社区](https://openeuler.org/)网站“文档->20.09”。 + + +### 如何参与SIG +建立或回复 issue：欢迎通过建立或回复 issue 来讨论。 +提交PR：欢迎通过提交PR的方式参与SIG。具体操作方法可参考[PR提交指南](https://gitee.com/openeuler/community/blob/master/zh/contributors/pull-request.md)。 +提交评论：欢迎在issue或PR中提交评论。 +重要的事说三遍：欢迎提交 PR！欢迎提交 PR！欢迎提交 PR！ + +### 成员 +#### Maintainer 列表 +- Rudy_Tan(@rudy_tan) +- amyMaYun(@amy_mayun) +- qiaominna(@qiaominna) + +### 如何联系我们 +邮件列表: dev@openeuler.org +IRC: #openeuler-doc \ No newline at end of file diff --git a/docs/en/docs/20.09/docs/A-Tune/installation-and-deployment.md b/docs/en/docs/20.09/docs/A-Tune/installation-and-deployment.md index 6b9b5bd530908a0eff76d74de2aa87396bd1df54..68c0e2081d25dfd208d2692cc8f40ce1fcccc9a4 100644 --- a/docs/en/docs/20.09/docs/A-Tune/installation-and-deployment.md +++ b/docs/en/docs/20.09/docs/A-Tune/installation-and-deployment.md @@ -22,11 +22,11 @@ This chapter describes how to install and deploy A-Tune. ### Software Requirement -- OS: openEuler 20.03 LTS +- OS: openEuler 20.09 ## Environment Preparation -For details about installing an openEuler OS, see _openEuler 20.03 LTS Installation Guide_. +For details about installing an openEuler OS, see _openEuler 20.09 Installation Guide_. ## A-Tune Installation @@ -58,7 +58,7 @@ To install the A-Tune, perform the following steps: 1. Mount an openEuler ISO file. ``` - # mount openEuler-20.03-LTS-aarch64-dvd.iso /mnt + # mount openEuler-20.09-aarch64-dvd.iso /mnt ``` 2. Configure the local yum source. diff --git a/docs/en/docs/20.09/docs/Administration/figures/ima_digest_list_update.png b/docs/en/docs/20.09/docs/Administration/figures/ima_digest_list_update.png new file mode 100644 index 0000000000000000000000000000000000000000..771067e31cee84591fbb914d7be4e8c576d7f5d2 Binary files /dev/null and b/docs/en/docs/20.09/docs/Administration/figures/ima_digest_list_update.png differ diff --git a/docs/en/docs/20.09/docs/Administration/figures/ima_performance.PNG b/docs/en/docs/20.09/docs/Administration/figures/ima_performance.PNG new file mode 100644 index 0000000000000000000000000000000000000000..f5d641e8682ad2b9c0fbfad191add1819f5b2eef Binary files /dev/null and b/docs/en/docs/20.09/docs/Administration/figures/ima_performance.PNG differ diff --git a/docs/en/docs/20.09/docs/Administration/figures/ima_verification.png b/docs/en/docs/20.09/docs/Administration/figures/ima_verification.png new file mode 100644 index 0000000000000000000000000000000000000000..fc879949db5387c61ccf6176f948b9a00f4fb053 Binary files /dev/null and b/docs/en/docs/20.09/docs/Administration/figures/ima_verification.png differ diff --git a/docs/en/docs/20.09/docs/Administration/figures/trusted_chain.png b/docs/en/docs/20.09/docs/Administration/figures/trusted_chain.png new file mode 100644 index 0000000000000000000000000000000000000000..034f0f092f41fb500ee4122339c447d10d4138ec Binary files /dev/null and b/docs/en/docs/20.09/docs/Administration/figures/trusted_chain.png differ diff --git a/docs/en/docs/20.09/docs/Administration/trusted-computing.md b/docs/en/docs/20.09/docs/Administration/trusted-computing.md new file mode 100644 index 0000000000000000000000000000000000000000..8f99120dae3f8ccf92551a70735e9afb2214906d --- /dev/null +++ b/docs/en/docs/20.09/docs/Administration/trusted-computing.md @@ -0,0 +1,638 @@ +# Trusted Computing + + +- [Trusted Computing](#可信计算) + - [Trusted Computing Basics](#可信计算基础) + - [Trusted Computing](#可信计算-1) + - [Kernel Integrity Measurement Architecture (IMA)](#内核完整性度量ima) + - [Overview](#概述) + - [Constraints](#约束限制) + - [Application Scenarios](#使用场景) + - [Procedure](#操作指导) + - [FAQ](#faq) + - [Appendix](#附录) + + +## Trusted Computing Basics + +### Trusted Computing + +The definition of being trusted varies with international organizations. + +1. Trusted Computing Group (TCG): + + An entity that is trusted always achieves the desired goal in an expected way. + +2. International Organization for Standardization (ISO) and International Electrotechnical Commission (IEC) (1999): + + The components, operations, or processes involved in computing are predictable under any conditions and are resistant to viruses and a certain degree of physical interference. + +3. IEEE Computer Society Technical Committee on Dependable Computing: + + Being trusted means that the services provided by the computer system can be proved to be reliable, and mainly refers to the reliability and availability of the system. + +In short, being trusted means that the system operates according to a pre-determined design and policy. + +A trusted computing system consists of a root of trust, a trusted hardware platform, operating system (OS), and application. The basic idea of the system is to create a trusted computing base (TCB) first, and then establish a trust chain that covers the hardware platform, OS, and application. In the trust chain, authentication is performed from the root to the next level, extending trust level by level and building a secure and trusted computing environment. + +![](./figures/trusted_chain.png) + +Unlike the traditional security mechanism that eliminates viruses without solving the root of the problem, trusted computing adopts the whitelist mechanism to allow only authorized kernels, kernel modules, and applications to run on the system. The system will reject the execution of a program that is unknown or has been changed. + +## Kernel Integrity Measurement Architecture (IMA) + +### Overview + +#### IMA + +The integrity measurement architecture (IMA) is a subsystem in the kernel. The IMA can measure files accessed through **execve()**, **mmap()**, and **open()** systems based on user-defined policies. The measurement result can be used for **local or remote attestation**, or can be compared with an existing reference value to **control the access to files**. + +According to the Wiki definition, the function of the kernel integrity subsystem include three parts: + +- Measure: Detects accidental or malicious modifications to files, either remotely or locally. +- Appraise: Measures a file and compares it with a reference value stored in the extended attribute to control the integrity of the local file. +- Audit: Writes the measurement result into system logs for auditing. + +Figuratively, IMA measurement is an observer that only records modification without interfering in it, and IMA appraisal is more like a strict security guard that rejects any unauthorized access to programs. + +#### EVM + +The extended verification module (EVM) is used to calculate a hash value based on the security extended attributes of a file in the system, including **security.ima** and **security.selinux**. Then this value is signed by the key stored in the TPM or other trusted environments. The signature value is stored in **security.evm** and cannot be tampered with. If the value is tampered with, the signature verification fails when the file is accessed again. + +In summary, the EVM is used to provide offline protection for security extended attributes by calculating the digest of the attributes and signing and storing them in **security.evm**. + +#### IMA Digest Lists + +IMA Digest Lists are an enhancement of the original kernel integrity protection mechanism provided by openEuler. It replaces the original IMA mechanism to protect file integrity. + +Digest lists are binary data files in a special format. Each digest list corresponds to an RPM package and records the hash values of protected files (executable files and dynamic library files) in the RPM package. + +After the startup parameters are correctly configured, the kernel maintains a hash table (invisible to the user space) and provides interfaces (**digest\_list\_data** and **digest\_list\_data\_del**) that update the hash table using **securityfs**. The digest lists are signed by the private key when they are built. When uploaded to the kernel through the interface, the digest lists need to be verified by the public key in the kernel. + +![](./figures/ima_digest_list_update.png) + +When IMA appraisal is enabled, each time an executable file or dynamic library file is accessed, the hook in the kernel is invoked to calculate the hash values of the file content and extended attributes and search in the kernel hash table. If the calculated hash values match the one in the table, the file is allowed to be executed. Otherwise, the access is denied. + +![1599719649188](./figures/ima_verification.png) + +The IMA Digest Lists extension provided by the openEuler kernel provides higher security, performance, and usability than the native IMA mechanism of the kernel community, facilitating the implementation of the integrity protection mechanism in the production environment. + +- **A complete trust chain for high security** + + The native IMA mechanism requires that the file extended attribute be generated and marked in advance on the live network. When the file is accessed, the file extended attribute is used as a reference value, resulting in an incomplete trust chain. + + The IMA Digest Lists extension saves the reference digest value of the file in the kernel space. During the construction, the reference digest value of the file is carried in the released RPM package in the form of a digest list. When the RPM package is installed, the digest list is imported and the signature is verified, ensuring that the reference value comes from the software publisher and implementing a complete trust chain. + +- **Superior performance** + + The trusted platform module (TPM) chip is a low-speed chip, making the PCR extension operation a performance bottleneck in the IMA measurement scenario. To shatter this bottleneck, the Digest Lists extension reduces unnecessary PCR extension operations while ensuring security, providing 65% higher performance than the native IMA mechanism. + + In the IMA appraisal scenario, the Digest Lists extension performs signature verification in the startup phase to prevent signature verification from being performed each time the file is accessed. This helps deliver a 20% higher file access performance in the operation phase than that in the native IMA appraisal scenario. + +- **Fast deployment and smooth upgrade** + + When the native IMA mechanism is deployed for the first time or the software package is updated, you need to switch to the fix mode, manually mark the extended attributes of the file, and then restart the system to enter the enforcing mode. In this way, the installed program can be accessed normally. + + The Digest Lists extension can be used immediately after the installation is completed. In addition, the RPM package can be directly installed or upgraded in the enforcing mode without restarting the system or manually marking the extended attributes of the file. This minimizes user perception during the operation, allowing for quick deployment and smooth upgrade on the live network. + +Note: The IMA Digest Lists extension advances the signature verification of the native IMA to the startup phase. This causes the assumption that the memory in the kernel space cannot be tampered with. As a result, the IMA depends on other security mechanisms (secure startup of kernel module and dynamic memory measurement) to protect the integrity of the kernel memory. + +However, either the native IMA mechanism of the community or the IMA Digest Lists extension is only a link in the trust chain of trusted computing, and cannot ensure the system security alone. Security construction is always a systematic project that builds in-depth defense. + +### Constraints + +1. The current IMA appraisal mode can only protect immutable files in the system, including executable files and dynamic library files. +2. The IMA provides integrity measurement at the application layer. The security of the IMA depends on the reliability of the previous links. +3. Currently, the IMA does not support the import of the third-party application digest lists. +4. The startup log may contain `Unable to open file: /etc/keys/x509_ima.der`. This error is reported from the open source community and does not affect the use of the IMA digest lists feature. +5. In the ARM version, audit errors may occur when the log mode is enabled for the IMA. This occurs because the modprobe loads the kernel module before the digest lists are imported, but does not affect the normal functions. + +### Application Scenario + +#### IMA Measurement + +The purpose of IMA measurement is to detect unexpected or malicious modifications to system files. The measurement result can be used for local or remote attestation. + +If a TPM chip exists in the system, the measurement result is extended to a specified PCR register of the TPM chip. Due to the unidirectional PCR extension and the hardware security of the TPM chip, a user cannot modify the extended measurement result, thereby ensuring authenticity of the measurement result. + +The file scope and triggering conditions of IMA measurement can be configured by the user using the IMA policy. + +By default, IMA is disabled. However, the system searches for the **ima-policy** policy file in the `/etc/ima/` path. If the file is found, the system measures the files in the system based on the policy during startup. If you do not want to manually compile the policy file, you can configure the `ima_policy=tcb` in the startup parameters using the default policy. For details about more policy parameters, see the section *IMA Startup Parameters* in *Appendix*. + +You can check the currently loaded IMA policy in the `/sys/kernel/security/ima/policy` file. The IMA measurement log is located in the `/sys/kernel/security/ima/ascii_runtime_measurements` file, as shown in the following figure: + +```shell +$ head /sys/kernel/security/ima/ascii_runtime_measurements +10 ddee6004dc3bd4ee300406cd93181c5a2187b59b ima-ng sha1:9797edf8d0eed36b1cf92547816051c8af4e45ee boot_aggregate +10 180ecafba6fadbece09b057bcd0d55d39f1a8a52 ima-ng sha1:db82919bf7d1849ae9aba01e28e9be012823cf3a /init +10 ac792e08a7cf8de7656003125c7276968d84ea65 ima-ng sha1:f778e2082b08d21bbc59898f4775a75e8f2af4db /bin/bash +10 0a0d9258c151356204aea2498bbca4be34d6bb05 ima-ng sha1:b0ab2e7ebd22c4d17d975de0d881f52dc14359a7 /lib64/ld-2.27.so +10 0d6b1d90350778d58f1302d00e59493e11bc0011 ima-ng sha1:ce8204c948b9fe3ae67b94625ad620420c1dc838 /etc/ld.so.cache +10 d69ac2c1d60d28b2da07c7f0cbd49e31e9cca277 ima-ng sha1:8526466068709356630490ff5196c95a186092b8 /lib64/libreadline.so.7.0 +10 ef3212c12d1fbb94de9534b0bbd9f0c8ea50a77b ima-ng sha1:f80ba92b8a6e390a80a7a3deef8eae921fc8ca4e /lib64/libc-2.27.so +10 f805861177a99c61eabebe21003b3c831ccf288b ima-ng sha1:261a3cd5863de3f2421662ba5b455df09d941168 /lib64/libncurses.so.6.1 +10 52f680881893b28e6f0ce2b132d723a885333500 ima-ng sha1:b953a3fa385e64dfe9927de94c33318d3de56260 /lib64/libnss_files-2.27.so +10 4da8ce3c51a7814d4e38be55a2a990a5ceec8b27 ima-ng sha1:99a9c095c7928ecca8c3a4bc44b06246fc5f49de /etc/passwd +``` + +From left to right, the content of each record indicates: + +1. PCR: PCR register for extending measurement results (The default value is 10. This register is valid only when the TPM chip is installed in the system.) +2. Template hash value: hash value that is finally used for extension, combining the file content hash and the length and value of the file path +3. Template: template of the extended measurement value, for example, **ima-ng** +4. File content hash value: hash value of the measured file content +5. File path: path of the measured file + +#### IMA Appraisal + +The purpose of IMA appraisal is to control access to local files by comparing the reference value with the standard reference value. + +IMA uses the security extension attributes **security.ima** and **security.evm** to store the reference values of file integrity measurement. + +- **security.ima**: stores the hash value of the file content +- **security.evm**: stores the hash value signature of a file extended attribute + +When a protected file is accessed, the hook in the kernel is triggered to verify the integrity of the extended attributes and content of the file. + +1. Use the public key in the kernel keyring to verify the signature value in the extended attribute of the **security.evm** file, and compare this signature value with the hash value of the extended attribute of the current file. If they match, the extended attribute of the file is complete (including **security.ima**). +2. When the extended attribute of the file is complete, the system compares the extended attribute of the file **security.ima** with the digest value of the current file content. If they match, the system allows for the access to the file. + +Likewise, the file scope and trigger conditions for IMA appraisal can be configured by users using IMA policies. + +#### IMA Digest Lists + +Currently, the IMA Digest Lists extension supports the following three combinations of startup parameters: + +* IMA measurement mode: + + ```shell + ima_policy=exec_tcb ima_digest_list_pcr=11 + ``` + +* IMA appraisal log mode + IMA measurement mode: + + ```shell + ima_template=ima-sig ima_policy="exec_tcb|appraise_exec_tcb|appraise_exec_immutable" initramtmpfs ima_hash=sha256 ima_appraise=log evm=allow_metadata_writes evm=x509 ima_digest_list_pcr=11 ima_appraise_digest_list=digest + ``` + +* IMA appraisal enforcing mode + IMA measurement mode: + + ```shell + ima_template=ima-sig ima_policy="exec_tcb|appraise_exec_tcb|appraise_exec_immutable" initramtmpfs ima_hash=sha256 ima_appraise=enforce-evm evm=allow_metadata_writes evm=x509 ima_digest_list_pcr=11 ima_appraise_digest_list=digest + ``` + +### Procedure + +#### Initial Deployment in the Native IMA Scenario + +When the system is started for the first time, you need to configure the following startup parameters: + +```shell +ima_appraise=fix ima_policy=appraise_tcb +``` + +In the `fix` mode, the system can be started when no reference value is available. `appraise_tcb` corresponds to an IMA policy. For details, see *IMA Startup Parameters* in the *Appendix*. + +Next, you need to access all the files that need to be verified to add IMA extended attributes to them: + +```shell +$ time find / -fstype ext4 -type f -uid 0 -exec dd if='{}' of=/dev/null count=0 status=none \; +``` + +This process takes some time. After the command is executed, you can see the marked reference value in the extended attributes of the protected file. + +```shell +$ getfattr -m - -d /sbin/init +# file: sbin/init +security.ima=0sAXr7Qmun5mkGDS286oZxCpdGEuKT +security.selinux="system_u:object_r:init_exec_t" +``` + +Configure the following startup parameters and restart the system: + +```shell +ima_appraise=enforce ima_policy=appraise_tcb +``` + +#### Initial Deployment in the Digest Lists Scenario + +1. Set kernel parameters to enter the log mode. + + Add the following parameters to edit the `/boot/efi/EFI/euleros/grub.cfg` file: + + ```shell + ima_template=ima-sig ima_policy="exec_tcb|appraise_exec_tcb|appraise_exec_immutable" initramtmpfs ima_hash=sha256 ima_appraise=log evm=allow_metadata_writes evm=x509 ima_digest_list_pcr=11 ima_appraise_digest_list=digest + ``` + + Run the `reboot` command to restart the system and enter the log mode. In this mode, integrity check has been enabled, but the system can be started even if the check fails. + +2. Install the dependency package. + + Run the **yum** command to install **digest-list-tools** and **ima-evm-utils**. Ensure that the versions are not earlier than the following: + + ```shell + $ yum install digest-list-tools ima-evm-utils + $ rpm -qa | grep digest-list-tools + digest-list-tools-0.3.93-1.oe1.x86_64 + $ rpm -qa | grep ima-evm-utils + ima-evm-utils-1.2.1-9.oe1.x86_64 + ``` + +3. If the **plymouth** package is installed, you need to add `-a` to the end of the **cp** command in line 147 in the `/usr/libexec/plymouth/plymouth-populate-initrd` script file: + + ```shell + ... + ddebug "Installing $_src" + cp -a --sparse=always -pfL "$PLYMOUTH_SYSROOT$_src" "${initdir}/$target" + } + ``` + +4. Run `dracut` to generate **initrd** again: + + ```shell + $ dracut -f -e xattr + ``` + + Edit the `/boot/efi/EFI/euleros/grub.cfg` file by changing **ima\_appraise=log** to **ima\_appraise=enforce-evm**. + + ```shell + ima_template=ima-sig ima_policy="exec_tcb|appraise_exec_tcb|appraise_exec_immutable" initramtmpfs ima_hash=sha256 ima_appraise=enforce-evm evm=allow_metadata_writes evm=x509 ima_digest_list_pcr=11 ima_appraise_digest_list=digest + ``` + + Run the **reboot** command to complete the initial deployment. + +#### Building Digest Lists on OBS + +Open Build Service (OBS) is a compilation system that was first used for building software packages in openSUSE and supports distributed compilation of multiple architectures. + +Before building a digest list, ensure that your project contains the following RPM packages from openEuler: + +* digest-list-tools +* pesign-obs-integration +* selinux-policy +* rpm +* openEuler-rpm-config + +Add **Project Config** in the deliverable project: + +```shell +Preinstall: pesign-obs-integration digest-list-tools selinux-policy-targeted +Macros: +%__brp_digest_list /usr/lib/rpm/openEuler/brp-digest-list %{buildroot} +:Macros +``` + +* The following content is added to **Preinstall**: **digest-list-tools** for generating the digest list; **pesign-obs-integration** for generating the digest list signature; **selinux-policy-targeted**, ensuring that the SELinux label in the environment is correct when the digest list is generated. +* Define the macro **%\_\_brp\_digest\_list** in Macros. The RPM runs this macro to generate a digest list for the compiled binary file in the build phase. This macro can be used as a switch to control whether the digest list is generated in the project. + +After the configuration is completed, OBS automatically performs full build. In normal cases, the following two files are added to the software package: + +* **/etc/ima/digest\_lists/0-metadata\_list-compact-\[package name]-\[version number]** +* **/etc/ima/digest\_lists.tlv/0-metadata\_list-compact\_tlv-\[package name]-\[version number]** + +#### Building Digest Lists on Koji + +Koji is a compilation system of the Fedora community. The openEuler community will support Koji in the future. + +### FAQ + +1. Why does the system fail to be started, or commands fail to be executed, or services are abnormal after the system is started in enforcing mode? + + In enforcing mode, IMA controls file access. If the content or extended attributes of a file to be accessed are incomplete, the access will be denied. If key commands that affect system startup cannot be executed, the system cannot be started. + + Check whether the following problems exist: + + * **Check whether the digest list is added to initrd.** + + Check whether the **dracut** command is executed to add the digest list to the kernel during the initial deployment. If the digest list is not added to **initrd**, the digest list cannot be imported during startup. As a result, the startup fails. + + * **Check whether the official RPM package is used.** + + If a non-official openEuler RPM package is used, the RPM package may not carry the digest list, or the private key for signing the digest list does not match the public key for signature verification in the kernel. As a result, the digest list is not imported to the kernel. + + If the cause is not clear, enter the log mode and find the cause from the error log: + + ```shell + $ dmesg | grep appraise + ``` + +2. Why access control is not performed on system files in enforcing mode? + + When the system does not perform access control on the file as expected, check whether the IMA policy in the startup parameters is correctly configured: + + ```shell + $ cat /proc/cmdline + ...ima_policy=exec_tcb|appraise_exec_tcb|appraise_exec_immutable... + ``` + + Run the following command to check whether the IMA policy in the current kernel has taken effect: + + ```shell + $ cat /sys/kernel/security/ima/policy + ``` + + If the policy file is empty, it indicates that the policy fails to be set. In this case, the system does not perform access control. + +3. After the initial deployment is completed, do I need to manually run the **dracut** command to generate **initrd** after installing, upgrading, or uninstalling the software package? + + No. The **digest\_list.so** plug-in provided by the RPM package can automatically update the digest list at the RPM package granularity, allowing users to be unaware of the digest list. + +### Appendix + +#### Description of the IMA securityfs Interface + +The native IMA provides the following **securityfs** interfaces: + +> Note: The following interface paths are in the `/sys/kernel/security/` directory. + +| Path | Permission | Description | +| ------------------------------ | ---------- | ------------------------------------------------------------ | +| ima/policy | 600 | IMA policy interface | +| ima/ascii_runtime_measurement | 440 | IMA measurement result in ASCII code format | +| ima/binary_runtime_measurement | 440 | IMA measurement result in binary format | +| ima/runtime_measurement_count | 440 | Measurement result statistics | +| ima/violations | 440 | Number of IMA measurement result conflicts | +| evm | 660 | EVM mode, that is, the mode for verifying the integrity of extended attributes of files | + +The values of `/sys/kernel/security/evm` are as follows: + +* 0: EVM uninitialized. +* 1: Uses HMAC (symmetric encryption) to verify the integrity of extended attributes. +* 2: Uses the public key signature (asymmetric encryption) to verify the integrity of extended attributes. +* 6: Disables the integrity check of extended attributes (This mode is used for openEuler). + +The additional **securityfs** interfaces provided by the IMA Digest Lists extension are as follows: + +| Path | Permission | Description | +| ------------------------ | ---------- | ---------------------------------------------------------- | +| ima/digests_count | 440 | Total number of digests (IMA+EVM) in the system hash table | +| ima/digest_list_data | 200 | New interfaces in the digest list | +| ima/digest_list_data_del | 200 | Interfaces deleted from the digest list | + +#### IMA Policy Syntax + +Each IMA policy statement must start with an **action** represented by the keyword action and be followed by a **filtering condition**: + +- **action**: indicates the action of a policy. Only one **action** can be selected for a policy. + + > Note: You can **ignore the word action** and directly write **dont\_measure** instead of **action=dont\_measure**. + +- **func**: indicates the type of the file to be measured or authenticated. It is often used together with **mask**. Only one **func** can be selected for a policy. + + - **FILE\_CHECK** can be used only with **MAY\_EXEC**, **MAY\_WRITE**, and **MAY\_READ**. + - **MODULE\_CHECK**, **MMAP\_CHECK**, and **BPRM\_CHECK** can be used only with **MAY\_EXEC**. + - A combination without the preceding matching relationships does not take effect. + +- **mask**: indicates the operation upon which files will be measured or appraised. Only one **mask** can be selected for a policy. + +- **fsmagic**: indicates the hexadecimal magic number of the file system type, which is defined in the `/usr/include/linux/magic.h` file. + + > Note: By default, all file systems are measured unless you use the **dont\_measure/dont\_appraise** to mark a file system not to be measured. + +- **fsuid**: indicates the UUID of a system device. The value is a hexadecimal string of 16 characters. + +- **objtype**: indicates the file type. Only one file type can be selected for a policy. + + > Note: **objtype** has a finer granularity than **func**. For example, **obj\_type=nova\_log\_t** indicates the nova log file. + +- **uid**: indicates the user (represented by the user ID) who performs operations on the file. Only one **uid** can be selected for a policy. + +- **fowner**: indicates the owner (represented by the user ID) of the file. Only one **fowner** can be selected for a policy. + +The values and description of the keywords are as follows: + +| Keyword | Value | Description | +| ------------- | ------------------ | ------------------------------------------------------------ | +| action | measure | Enables IMA measurement | +| | dont_measure | Disables IMA measurement | +| | appraise | Enables IMA appraisal | +| | dont_appraise | Disables IMA appraisal | +| | audit | Enables audit | +| func | FILE_CHECK | File to be opened | +| | MODULE_CHECK | Kernel module file to be loaded | +| | MMAP_CHECK | Dynamic library file to be mapped to the memory space of the process | +| | BRPM_CHECK | File to be executed (excluding script files opened by programs such as `/bin/hash`) | +| | POLICY_CHECK | File to be loaded as a supplement to the IMA policy | +| | FIRMWARE_CHECK | Firmware to be loaded into memory | +| | DIGEST_LIST_CHECK | Digest list file to be loaded into the kernel | +| | KEXEC_KERNEL_CHECK | kexec kernel to be switched to | +| mask | MAY_EXEC | Executes a file | +| | MAY_WRITE | Writes data to a file This operation is not recommended because it is restricted by open source mechanisms such as echo and vim (the essence of modification is to create a temporary file and then rename it). The IMA measurement of **MAY\_WRITE** is not triggered each time the file is modified. | +| | MAY_READ | Reads a file | +| | MAY_APPEND | Extends file attributes | +| fsmagic | fsmagic=xxx | Hexadecimal magic number of the file system type | +| fsuuid | fsuuid=xxx | UUID of a system device. The value is a hexadecimal string of 16 characters. | +| fowner | fowner=xxx | User ID of the file owner | +| uid | uid=xxx | ID of the user who operates the file | +| obj_type | obj_type=xxx_t | File type (based on the SELinux tag) | +| pcr | pcr= | Selects the PCR used to extend the measurement values in the TPM. The default value is 10. | +| appraise_type | imasig | Signature-based IMA appraisal | +| | meta_immutable | Evaluates the extended attributes of the file based on signatures (supporting the digest list). | + +> Note: **PATH\_CHECK** is equivalent to **FILE\_CHECK**, and **FILE\_MMAP** is equivalent to **MMAP\_CHECK**. They are not mentioned in this table. + +#### IMA Native Startup Parameters + +The following table lists the kernel startup parameters of the native IMA. + +| Parameter | Value | Description | +| ---------------- | ------------ | ------------------------------------------------------------ | +| ima_appraise | off | Disables the IMA appraisal mode. The integrity check is not performed when the file is accessed and no new reference value is generated for the file. | +| | enforce | Enables the IMA appraisal enforcing mode to perform the integrity check when the file is accessed. That is, the file digest value is calculated and compared with the reference value. If the comparison fails, the file access is rejected. In this case, the IMA generates a new reference value for the new file. | +| | fix | Enables the IMA repair mode. In this mode, the reference value of a protected file can be updated. | +| | log | Enables the IMA appraisal log mode to perform the integrity check when the file is accessed. However, commands can be executed even if the check fails, and only logs are recorded. | +| ima_policy | tcb | Measures all file execution, dynamic library mapping, kernel module import, and device driver loading. The file read behavior of the root user is also measured. | +| | appraise_tcb | Evaluates all files whose owner is the root user. | +| | secure_boot | Evaluates the kernel module import, hardware driver loading, kexec kernel switchover, and IMA policies. The prerequisite is that these files have IMA signatures. | +| ima_tcb | None | Equivalent to **ima\_policy=tcb**. | +| ima_appraise_tcb | None | Equivalent to **ima\_policy=appraise\_tcb**. | +| ima_hash | sha1/md5/... | IMA digest algorithm. The default value is sha1. | +| ima_template | ima | IMA measurement extension template | +| | ima-ng | IMA measurement extension template | +| | ima-sig | IMA measurement extension template | +| integrity_audit | 0 | Basic integrity audit information (default) | +| | 1 | Additional integrity audit information | + +> Note: The **ima\_policy** parameter can specify multiple values at the same time, for example, **ima\_policy=tcb\|appraise\_tcb**. After the system is started, the IMA policy of the system is the sum of the policies for the two parameters. + +The IMA policy for the `ima_policy=tcb` startup parameter is as follows: + +``` +# PROC_SUPER_MAGIC = 0x9fa0 +dont_measure fsmagic=0x9fa0 +# SYSFS_MAGIC = 0x62656572 +dont_measure fsmagic=0x62656572 +# DEBUGFS_MAGIC = 0x64626720 +dont_measure fsmagic=0x64626720 +# TMPFS_MAGIC = 0x01021994 +dont_measure fsmagic=0x1021994 +# DEVPTS_SUPER_MAGIC=0x1cd1 +dont_measure fsmagic=0x1cd1 +# BINFMTFS_MAGIC=0x42494e4d +dont_measure fsmagic=0x42494e4d +# SECURITYFS_MAGIC=0x73636673 +dont_measure fsmagic=0x73636673 +# SELINUX_MAGIC=0xf97cff8c +dont_measure fsmagic=0xf97cff8c +# SMACK_MAGIC=0x43415d53 +dont_measure fsmagic=0x43415d53 +# CGROUP_SUPER_MAGIC=0x27e0eb +dont_measure fsmagic=0x27e0eb +# CGROUP2_SUPER_MAGIC=0x63677270 +dont_measure fsmagic=0x63677270 +# NSFS_MAGIC=0x6e736673 +dont_measure fsmagic=0x6e736673 +measure func=MMAP_CHECK mask=MAY_EXEC +measure func=BPRM_CHECK mask=MAY_EXEC +measure func=FILE_CHECK mask=MAY_READ uid=0 +measure func=MODULE_CHECK +measure func=FIRMWARE_CHECK +``` + +The IMA policy for the `ima_policy=tcb_appraise` startup parameter is as follows: + +``` +# PROC_SUPER_MAGIC = 0x9fa0 +dont_appraise fsmagic=0x9fa0 +# SYSFS_MAGIC = 0x62656572 +dont_appraise fsmagic=0x62656572 +# DEBUGFS_MAGIC = 0x64626720 +dont_appraise fsmagic=0x64626720 +# TMPFS_MAGIC = 0x01021994 +dont_appraise fsmagic=0x1021994 +# RAMFS_MAGIC +dont_appraise fsmagic=0x858458f6 +# DEVPTS_SUPER_MAGIC=0x1cd1 +dont_appraise fsmagic=0x1cd1 +# BINFMTFS_MAGIC=0x42494e4d +dont_appraise fsmagic=0x42494e4d +# SECURITYFS_MAGIC=0x73636673 +dont_appraise fsmagic=0x73636673 +# SELINUX_MAGIC=0xf97cff8c +dont_appraise fsmagic=0xf97cff8c +# SMACK_MAGIC=0x43415d53 +dont_appraise fsmagic=0x43415d53 +# NSFS_MAGIC=0x6e736673 +dont_appraise fsmagic=0x6e736673 +# CGROUP_SUPER_MAGIC=0x27e0eb +dont_appraise fsmagic=0x27e0eb +# CGROUP2_SUPER_MAGIC=0x63677270 +dont_appraise fsmagic=0x63677270 +appraise fowner=0 +``` + +The IMA policy for the `ima_policy=secure_boot` startup parameter is as follows: + +``` +appraise func=MODULE_CHECK appraise_type=imasig +appraise func=FIRMWARE_CHECK appraise_type=imasig +appraise func=KEXEC_KERNEL_CHECK appraise_type=imasig +appraise func=POLICY_CHECK appraise_type=imasig +``` + +#### IMA Digest List Startup Parameters + +The kernel startup parameters added to the IMA digest list feature are as follows: + +| Parameter | Value | Description | +| ------------------------ | ----------------------- | ------------------------------------------------------------ | +| integrity | 0 | Disables the IMA feature (by default) | +| | 1 | Enables the IMA feature | +| ima_appraise | off | Disables the IMA appraisal mode | +| | enforce-evm | Enables the IMA appraisal forced mode to perform the integrity check when the file is accessed and control the access. | +| ima_appraise_digest_list | digest | When the EVM is disabled, the abstract list is used for IMA appraise. The abstract list protects both the content and extended attributes of the file. | +| | digest-nometadata | If the EVM digest value does not exist, the integrity check is performed only based on the IMA digest value (the file extended attribute is not protected). | +| evm | fix | Allows for any modification to the extended attribute (even if the modification causes the failure to verify the integrity of the extended attribute). | +| | ignore | Allowed to modify the extended attribute only when it does not exist or is incorrect. | +| ima_policy | exec_tcb | IMA measurement policy. For details, see the following policy description. | +| | appraise_exec_tcb | IMA appraisal policy. For details, see the following policy description. | +| | appraise_exec_immutable | IMA appraisal policy. For details, see the following policy description. | +| ima_digest_list_pcr | 11 | Uses PCR 11 instead of PCR 10, and uses only the digest list for measurement. | +| | +11 | The PCR 10 measurement is reserved. When the TPM chip is available, the measurement result is written to the TPM chip. | +| initramtmpfs | None | Adds the support for **tmpfs**. | + + + +The IMA policy for the `ima_policy=exec_tcb` startup parameter is as follows: + +``` +dont_measure fsmagic=0x9fa0 +dont_measure fsmagic=0x62656572 +dont_measure fsmagic=0x64626720 +dont_measure fsmagic=0x1cd1 +dont_measure fsmagic=0x42494e4d +dont_measure fsmagic=0x73636673 +dont_measure fsmagic=0xf97cff8c +dont_measure fsmagic=0x43415d53 +dont_measure fsmagic=0x27e0eb +dont_measure fsmagic=0x63677270 +dont_measure fsmagic=0x6e736673 +measure func=MMAP_CHECK mask=MAY_EXEC +measure func=BPRM_CHECK mask=MAY_EXEC +measure func=MODULE_CHECK +measure func=FIRMWARE_CHECK +measure func=POLICY_CHECK +measure func=DIGEST_LIST_CHECK +measure parser +``` + +The IMA policy for the `ima_policy=appraise_exec_tcb` startup parameter is as follows: + +``` +appraise func=MODULE_CHECK appraise_type=imasig +appraise func=FIRMWARE_CHECK appraise_type=imasig +appraise func=KEXEC_KERNEL_CHECK appraise_type=imasig +appraise func=POLICY_CHECK appraise_type=imasig +appraise func=DIGEST_LIST_CHECK appraise_type=imasig +dont_appraise fsmagic=0x9fa0 +dont_appraise fsmagic=0x62656572 +dont_appraise fsmagic=0x64626720 +dont_appraise fsmagic=0x858458f6 +dont_appraise fsmagic=0x1cd1 +dont_appraise fsmagic=0x42494e4d +dont_appraise fsmagic=0x73636673 +dont_appraise fsmagic=0xf97cff8c +dont_appraise fsmagic=0x43415d53 +dont_appraise fsmagic=0x6e736673 +dont_appraise fsmagic=0x27e0eb +dont_appraise fsmagic=0x63677270 +``` + +The IMA policy for the `ima_policy=appraise_exec_immutable` startup parameter is as follows: + +``` +appraise func=BPRM_CHECK appraise_type=imasig appraise_type=meta_immutable +appraise func=MMAP_CHECK +appraise parser appraise_type=imasig +``` + +#### IMA Kernel Compilation Options + +The native IMA provides the following compilation options: + +| Compilation Option | Description | +| -------------------------------- | ------------------------------------------------------- | +| CONFIG_INTEGRITY | IMA/EVM compilation switch | +| CONFIG_INTEGRITY_SIGNATURE | Enables IMA signature verification | +| CONFIG_INTEGRITY_ASYMMETRIC_KEYS | Enables IMA asymmetric signature verification | +| CONFIG_INTEGRITY_TRUSTED_KEYRING | Enables IMA/EVM key ring | +| CONFIG_INTEGRITY_AUDIT | Compiles the IMA audit module | +| CONFIG_IMA | IMA compilation switch | +| CONFIG_IMA_WRITE_POLICY | Allows updating the IMA policy in the running phase | +| CONFIG_IMA_MEASURE_PCR_IDX | Allows specifying the PCR number of the IMA measurement | +| CONFIG_IMA_LSM_RULES | Allows configuring LSM rules | +| CONFIG_IMA_APPRAISE | IMA appraisal compilation switch | +| IMA_APPRAISE_BOOTPARAM | Enables IMA appraisal startup parameters | +| CONFIG_EVM | EVM compilation switch | + +The additional compilation options provided by the IMA Digest Lists extension are as follows: + +| Compilation Option | Description | +| ------------------ | ----------------------------------- | +| CONFIG_DIGEST_LIST | Enables the IMA Digest List feature | + +#### IMA Performance Reference Data + +The following figure compares the performance when IMA is disabled, native IMA is enabled, and IMA digest list is enabled. + +![img](./figures/ima_performance.gif) \ No newline at end of file diff --git a/docs/en/docs/20.09/docs/ApplicationDev/FAQ.md b/docs/en/docs/20.09/docs/ApplicationDev/FAQ.md new file mode 100644 index 0000000000000000000000000000000000000000..8b355eeed2a4e1db834a8383829dfebc77752f89 --- /dev/null +++ b/docs/en/docs/20.09/docs/ApplicationDev/FAQ.md @@ -0,0 +1,27 @@ +# FAQ + + + +- [FAQ](#faq) + - [The self-compilation of some applications that depend on the **java-devel** package fails.](#部分依赖java-devel的应用程序自编译失败) + + + +## The self-compilation of some applications that depend on the **java-devel** package fails. + +### Symptom + +The self-compilation of some applications that depend on java-devel fails when the rpmbuild command is executed. + +### Cause Analysis + +To provide OpenJDK features that are updated and compatible with Java applications, the openEuler provides OpenJDK of multiple versions, such as OpenJDK 1.8.0 and OpenJDK 11. The compilation of some applications depends on the **java-devel** package. When the **java-devel** package is installed, the system installs java-11-openjdk of a later version by default. As a result, the compilation of these applications fails. + +### Solution + +You need to run the following command to install java-1.8.0-openjdk and then run the **rpmbuild** command to perform self-compilation: + +``` +# yum install java-1.8.0-openjdk + +``` \ No newline at end of file diff --git a/docs/en/docs/20.09/docs/Container/isula-build.md b/docs/en/docs/20.09/docs/Container/isula-build.md index 986f85259b05df8d61d1b94b1ba416f8f89a0ff3..5b168754501bc7c896e8bc4d96786179e297c8c5 100644 --- a/docs/en/docs/20.09/docs/Container/isula-build.md +++ b/docs/en/docs/20.09/docs/Container/isula-build.md @@ -1,3 +1,5 @@ +# Container Image Building + @@ -35,6 +37,7 @@ +## Overview isula-build is a container image build tool developed by the iSula container team. It allows you to quickly build container images using Dockerfiles. @@ -46,9 +49,9 @@ Note: - Currently, isula-build supports only Docker images. -# Installation +## Installation -## Preparations +### Preparations To ensure that isula-build can be successfully installed, the following software and hardware requirements must be met: @@ -56,7 +59,7 @@ To ensure that isula-build can be successfully installed, the following software - Supported OS: openEuler - You have the permissions of the root user. -### Installing isula-build +#### Installing isula-build Before using isula-build to build a container image, you need to install the following software packages: @@ -89,9 +92,9 @@ Before using isula-build to build a container image, you need to install the fol > **Note:** After the installation is complete, you need to manually start the isula-build service. For details about how to start the service, see "Managing the isula-build Service." -# Configuring and Managing the isula-build Service +## Configuring and Managing the isula-build Service -## Configuring the isula-build Service +### Configuring the isula-build Service After the isula-build software package is installed, the systemd starts the isula-build service based on the default configuration contained in the isula-build software package on the isula-build server. If the default configuration file on the isula-build server cannot meet your requirements, perform the following operations to customize the configuration file: After the default configuration is modified, restart the isula-build server for the new configuration to take effect. For details, see "Managing the isula-build Service." @@ -136,14 +139,14 @@ Currently, the isula-build server contains the following configuration file: -## Managing the isula-build Service +### Managing the isula-build Service Currently, openEuler uses systemd to manage the isula-build service. The isula-build software package contains the systemd service file. After installing the isula-build software package, you can use the systemd tool to start or stop the isula-build service. You can also manually start the isula-builder software. Note that only one isula-builder process can be started on a node at a time. >![](./public_sys-resources/icon-note.gif) **Note:** > Only one isula-builder process can be started on a node at a time. -### (Recommended) Using systemd for Management +#### (Recommended) Using systemd for Management You can run the following systemd commands to start, stop, and restart the isula-build service: @@ -171,7 +174,7 @@ The systemd service file of the isula-build software installation package is sto sudo systemctl daemon-reload ``` -### Directly Running isula-builder +#### Directly Running isula-builder You can also run the isula-builder command on the server to start the service. The isula-builder command can contain flags for service startup. The following flags are supported: @@ -191,9 +194,9 @@ Start the isula-build service. For example, to specify the local persistency dir sudo isula-builder --dataroot "/var/lib/isula-build" --debug=false ``` -# Usage Guidelines +## Usage Guidelines -## Prerequisites +### Prerequisites isula-build depends on the executable file runc to build the RUN command in the Dockerfile. Therefore, the runc must be pre-installed in the running environment of isula-build. The installation method depends on the application scenario. If you do not need to use the complete docker-engine tool chain, you can install only the docker-runc RPM package. @@ -212,7 +215,7 @@ sudo yum install -y docker-engine -## Overview +### Overview The isula-build client provides a series of commands for building and managing container images. Currently, the isula-build client provides the following command lines: @@ -239,7 +242,7 @@ The following describes how to use these commands in detail. -## ctr-img: Container Image Management +### ctr-img: Container Image Management The isula-build command groups all container image management commands into the `ctr-img` command. The command is as follows: @@ -247,7 +250,7 @@ The isula-build command groups all container image management commands into the isula-build ctr-img [command] ``` -### build: Container Image Build +#### build: Container Image Build The subcommand build of the ctr-img command is used to build container images. The command is as follows: @@ -413,7 +416,7 @@ $ sudo isula-build ctr-img build --cap-add CAP_SYS_ADMIN --cap-add CAP_SYS_PTRAC -### image: Viewing Local Persistent Build Images +#### image: Viewing Local Persistent Build Images You can run the images command to view the images in the local persistent storage. @@ -431,7 +434,7 @@ localhost:5000/library/alpine latest a24bb4013296 -### import: Importing a Basic Container Image +#### import: Importing a Basic Container Image openEuler releases a basic container image, for example, openEuler-docker.x86_64.tar.xz, with the version. You can run the `ctr-img import` command to import the image to isula-build. @@ -444,13 +447,13 @@ isula-build ctr-img import [flags] Example: ```sh -$ sudo isula-build ctr-img import ./openEuler-docker.x86_64.tar.xz openeuler:20.03 +$ sudo isula-build ctr-img import ./openEuler-docker.x86_64.tar.xz openeuler:20.09 Import success with image id: 7317851cd2ab33263eb293f68efee9d724780251e4e92c0fb76bf5d3c5585e37 $ sudo isula-build ctr-img images ---------------------------------------------- -------------------- ----------------- ------------------------ ------------ REPOSITORY TAG IMAGE ID CREATED SIZE ---------------------------------------------- -------------------- ----------------- ------------------------ ------------ -openeuler 20.03 7317851cd2ab 2020-08-01 06:25:34 500 MB +openeuler 20.09 7317851cd2ab 2020-08-01 06:25:34 500 MB ---------------------------------------------- -------------------- ----------------- ------------------------ ------------ ``` @@ -459,7 +462,7 @@ openeuler 20.03 7317851cd2 -### load: Importing Cascade Images +#### load: Importing Cascade Images Cascade images are images that are saved to the local computer by running the docker save or isula-build ctr-img save command. The compressed image package contains a layer-by-layer image package named layer.tar. You can run the ctr-img load command to import the image to isula-build. @@ -505,7 +508,7 @@ Loaded image as c07ddb44daa97e9e8d2d68316b296cc9343ab5f3d2babc5e6e03b80cd580478e -### rm: Deleting a Local Persistent Image +#### rm: Deleting a Local Persistent Image You can run the rm command to delete an image from the local persistent storage. The command is as follows: @@ -528,7 +531,7 @@ Deleted: sha256:eeba1bfe9fca569a894d525ed291bdaef389d28a88c288914c1a9db7261ad12c -### save: Exporting Cascade Images +#### save: Exporting Cascade Images You can run the save command to export the cascade images to the local disk. The command is as follows: @@ -566,7 +569,7 @@ Save success with image: 21c3e96ac411 -### tag: Tagging Local Persistent Images +#### tag: Tagging Local Persistent Images You can run the tag command to add a tag to a local persistent container image. The command is as follows: @@ -595,7 +598,7 @@ alpine v1 a24bb4013296 -## info: Viewing the Operating Environment and System Information +### info: Viewing the Operating Environment and System Information You can run the isula-build info command to view the running environment and system information of isula-build. The command is as follows: @@ -632,7 +635,7 @@ $ sudo isula-build info -H oepkgs.net ``` -## login: Logging In to the Remote Image Repository +### login: Logging In to the Remote Image Repository You can run the login command to log in to the remote image repository. The command is as follows: @@ -663,7 +666,7 @@ Enter the password in interactive mode. Login Succeeded ``` -## logout: Logging Out of the Remote Image Repository +### logout: Logging Out of the Remote Image Repository You can run the logout command to log out of the remote image repository. The command is as follows: @@ -685,7 +688,7 @@ Example: Removed authentications ``` -## version: Querying the isula-build Version +### version: Querying the isula-build Version You can run the version command to view the current version information. @@ -707,11 +710,11 @@ You can run the version command to view the current version information. ``` -# Directly Integrating a Container Engine +## Directly Integrating a Container Engine isula-build can be integrated with iSulad or Docker to import the built container image to the local storage of the container engine. -## Integration with iSulad +### Integration with iSulad Images that are successfully built can be directly exported to the iSulad. @@ -734,7 +737,7 @@ busybox 2.0 2d414a5cad6d 2020-08-01 06:41: > - It is required that isula-build and iSulad be on the same node. > - When an image is directly exported to the iSulad, the isula-build client needs to temporarily store the successfully built image as `/var/tmp/isula-build-tmp-%v.tar` and then import it to the iSulad. Ensure that the /var/tmp/ directory has sufficient disk space. If the isula-build client process is killed or Ctrl+C is pressed during the export, you need to manually clear the `/var/tmp/isula-build-tmp-%v.tar` file. -## Integration with Docker +### Integration with Docker Images that are successfully built can be directly exported to the Docker daemon. @@ -756,10 +759,10 @@ busybox 2.0 2d414a5c > > - The isula-build and Docker must be on the same node. -# \Appendix +## \Appendix -## Command Line Parameters +### Command Line Parameters **Table 1** Parameters in the ctr-img build command @@ -806,11 +809,11 @@ busybox 2.0 2d414a5c | -------- | --------- | ------------------------------------ | | logout | -a, --all | Boolean, which indicates whether to log out of all logged-in image repositories. | -## Communication Matrix +### Communication Matrix The isula-build component processes communicate with each other through the Unix socket file. No port is used for communication. -## File and Permission +### File and Permission - All isula-build operations must be performed by the root user. diff --git a/docs/en/docs/20.09/docs/Releasenotes/key-features.md b/docs/en/docs/20.09/docs/Releasenotes/key-features.md index 9590ee5de7e7c3e07ea69341207b44d69c1db228..9659957c1734d0d1c73c610f142acfd5e6c2dc02 100644 --- a/docs/en/docs/20.09/docs/Releasenotes/key-features.md +++ b/docs/en/docs/20.09/docs/Releasenotes/key-features.md @@ -1,29 +1,49 @@ -# Key Features - -- iSula lightweight container solution, unified IoT, and edge and cloud computing container solutions - - Shortens a trace chain by three levels, and the memory usage of hundreds of containers is significantly lower than that of the Docker engine. - - Supports standard open-source container runtime interface \(CRI\) and open container initiative \(OCI\) and flexibly interconnects with multiple OCI runtimes such as runC and Kata. - - Secure container: combines the virtualization technology and container technology to ensure better isolation of secure containers. - - System container: supports local file system startup to implement quick deployment, and supports systemd deployment to improve user namespace isolation. - -- Kunpeng acceleration engine \(KAE\), supporting encryption and decryption acceleration - - Digest algorithm SM3, which supports asynchronous models. - - Symmetric encryption algorithm SM4, which supports asynchronous models and CTR, XTS, and CBC modes. - - Symmetric encryption algorithm AES, which supports asynchronous models and ECB, CTR, XTS, and CBC modes. - - Asymmetric algorithm RSA, which supports asynchronous models and key sizes 1024, 2048, 3072, and 4096. - - Key negotiation algorithm DH, which supports asynchronous models and key sizes 768, 1024, 1536, 2048, 3072, and 4096. - - -- A-Tune intelligent system performance optimization engine, inferring service features and configuring optimal system parameters to ensure optimal service running -- Enhancing the performance of glibc, zlib, and gzip and fully using the NEON instruction set of AArch64 to improve the basic library performance -- Kernel feature enhancement - - Supports ARM64 kernel hot patches. - - Numa Aware Qspinlock: reduces cache/bus conflicts across NUMA nodes. - - Optimizes the IOVA page table lookup and release algorithms to improve the performance of the IOMMU subsystem. - - Optimizes the implementation of CRC32 and checksum based on ARM64 instructions and pipeline features, greatly improving data verification performance. - - Supports ARM v8.4 Memory System Resource Partitioning and Monitoring \(MPAM\). -- virtualization feature enhancement - - Interruption virtualization optimization: The process for an IRQfd to inject an interrupt is optimized, greatly improving the performance of high-performance passthrough devices (sush as NICs and SSDs). - - Memory virtualization optimization: The Kunpeng hardware feature is used to improve the memory loading speed during VM startup. - - Storage virtualization optimization: NUMA affinity self-binding is optimized for the iSCSI module **kworker** to improve the I/O performance of IP SAN disks. +# Key Features +- StratoVirt: Combines high security and performance with lightweight loads, low power consumption, and flexible component splitting for universal VMs running in all scenarios. + + - Uses the Rust language, supports **seccomp** and multi-tenant isolation, providing a secure and trusted operating environment. + - Supports startup within 50 ms and memory noise floor of less than 4 MB, achieving the ultimate performance and lightweight deployment in various scenarios across-device-edge-cloud. + - Supports multiple hardware acceleration virtualized engines, such as x86 VT and Kunpeng-V. + - Supports device scaling within milliseconds, providing flexible resource scaling capabilities for lightweight loads. + - Scalable device models, supports complex device specifications such as PCI, and compatible with the QEMU software ecosystem. + - Supports multiple computing, network, and storage acceleration solutions, and flexible collaboration of heterogeneous computing power. + +- iSula: A lightweight container solution that unifies IoT, edge, and cloud computing. + + - Optimized operation performance for the startup and container lifecycle. + - **isula-build**, a container image build tool that provides secure and fast container image build capabilities. + - Secure and trusted VM startup for enhanced VM security. + +- Enhanced virtualization features + + - Optimizes VM lock preemption with dual-layer scheduling and Hypervisor-aware VM scheduling, delivering higher performance in the multi-core overcommitment scenario. + - Optimizes the IPI interruption performance using the Guest-Idle-Haltpoll mechanism, improving the database service performance. + - For the virtualization feature of the ARM platform, supports the CPU/memory hot plug and the custom mode for the KVM CPU, making resource configuration more flexible. + - Quickly collects performance indicators of a VM using the O\&M tool VMTOP. + - Enables hardlockup detection using the PMU NMI watchdog feature. + +- Kernel feature enhancement + + - Enhancement for IMA commercial use: Based on the open source IMA solution, improves security, performance, and usability to facilitate commercial use. + - NUMA Aware Qspinlock: Improves system performance by reducing cross-NUMA cache synchronization and ping-pong operations caused by lock competition. + - Ktask parallelism: A kernel task parallelism framework that supports the parallel operation of kernel tasks. + - MPAM resource control: Supports Cache QoS and memory bandwidth control technology for the ARM64 architecture. + - Memory system lock optimization: Optimizes vmalloc allocation lock and Pagecache lock. + +- Programming languages and compilers + + - JDK8 enhancement: Supports the APPCDS feature and crc32 hardware acceleration instruction. + - GCC optimization: Supports cyclic optimization, automatic vectorization, and global optimization. + +- Hardware and chip enablement + + - Raspberry Pi: Supports the Raspberry series boards. + +- Desktop support + + - UKUI: Default desktop environment of the Kylin OS. Its layout, style, and usage habits are similar to those of the traditional Windows OS. + +- Intelligent O\&M + + - A-Tune: An intelligent system performance optimization engine that infers service features and configures the optimal system parameter set for the optimal service operations. \ No newline at end of file diff --git a/docs/en/docs/20.09/docs/Releasenotes/known-issues.md b/docs/en/docs/20.09/docs/Releasenotes/known-issues.md index aad4be328d247d0ea0bf51c9163aaf856318f4e1..16ada9132ac580ad434b59d9b922e73649597fbb 100644 --- a/docs/en/docs/20.09/docs/Releasenotes/known-issues.md +++ b/docs/en/docs/20.09/docs/Releasenotes/known-issues.md @@ -1,11 +1,29 @@ -# Known Issues - -- The FIPS boot mode of the kernel has not been fully authenticated. The FIPS boot may be abnormal. [I17Z18](https://gitee.com/src-openeuler/crypto-policies/issues/I17Z18?from=project-issue) -- When libvirt is used to start the GlusterFS VM, a 300-byte memory leak occurs each time. For details about the discussion, click [https://github.com/gluster/glusterfs/issues/818](https://github.com/gluster/glusterfs/issues/818). [I185CH](https://gitee.com/src-openeuler/glusterfs/issues/I185CH?from=project-issue) -- When the libvirt interface is used to continuously perform disk hot swap operations, there is a possibility that the hot remove interface returns a success message, but the disk is not removed and cannot be hot swapped again. You can stop the VM and then restart it. [I1C72L](https://gitee.com/src-openeuler/qemu/issues/I1C72L?from=project-issue) -- There is a low probability that an unknown installation exception occurs when the x86\_64 VM is used for installation. In this case, install the x86\_64 VM again. [I1C8HS](https://gitee.com/src-openeuler/anaconda/issues/I1C8HS?from=project-issue) -- CVE-2012-0039: When a local application calls the **g\_str\_hash** function, the application continuously consumes CPU resources, causing DoS attacks. This issue will not be resolved in the community. -- CVE-2015-9541: When Qt attempts to parse the abnormal SVG files which are constructed to launch exponential XML entity extension attacks, the memory may be insufficient. For details about the discussion, click [https://codereview.qt-project.org/c/qt/qtbase/+/293909](https://codereview.qt-project.org/c/qt/qtbase/+/293909). -- Before compiling some open-source packages, you need to install basic software such as GDB, GCC, and make. Otherwise, the compilation fails due to lack of dependency. -- AArch64 and x86\_64 have different definitions of the character type. As a result, an error is reported during the self-check using Coreutils, Augeas, and Diffutils. You can add the **--fsigned-char** compilation option to solve the problem. +# Known Issues + + + + + + + + + + + + + + + + +

Issue

+

Description

+

I1VR1W

+

An error message is displayed when the x86 QCOW2 image is used for VM creation or the ISO image is used for physical machine installation. The error message is output as expected. For details, see the issue response.

+

I1U1LP

+

The ARM-based physical machine uses the drive that has been written into the file system for customized partitioning, but the partitioning fails. A special path can be used to prevent this issue. For details, see the issue response.

+

I1VTC5

+

In the pressure test in the overcommitment scenario, frame freezing occurs to vmtop -H page turning when the number of vCPUs is greater than 1,000. The impact scope is controllable. For details, see the issue response.

+

I1WVM8

+

Among the CPU usage data collected by vmtop, the single core whose usage exceeds 100% exists. The impact scope is controllable. For details, see the issue response.

+
diff --git a/docs/en/docs/20.09/docs/Releasenotes/resolved-issues.md b/docs/en/docs/20.09/docs/Releasenotes/resolved-issues.md index 5265bf49fee0fbf54acbaeb3eefb979676d30b31..01107f9b33cb9d4ebeb2f23e7e52130dd9a42951 100644 --- a/docs/en/docs/20.09/docs/Releasenotes/resolved-issues.md +++ b/docs/en/docs/20.09/docs/Releasenotes/resolved-issues.md @@ -1,75 +1,226 @@ -# Resolved Issues +# Resolved Issues -For details about the complete issue list, click [https://gitee.com/organizations/src-openeuler/issues](https://gitee.com/organizations/src-openeuler/issues). +For the complete issue list, see [Complete Issue List](https://gitee.com/organizations/src-openeuler/issues). -For details about the complete kernel submission records, click [https://gitee.com/openeuler/kernel/commits/openEuler-20.09](https://gitee.com/openeuler/kernel/commits/openEuler-20.09). +For details about the complete kernel submission records, see [Record Submission](https://gitee.com/openeuler/kernel/commits/openEuler-1.0-LTS). -[Table 1](#table249714911433) lists the resolved issues. +**Applications and basic services** -**Table 1** Resolved issues - - - diff --git "a/docs/zh/docs/20.09/docs/Releasenotes/\345\267\262\347\237\245\351\227\256\351\242\230.md" "b/docs/zh/docs/20.09/docs/Releasenotes/\345\267\262\347\237\245\351\227\256\351\242\230.md" index 3099acb599425b392e73513e8f6d5628d882e1ca..d759e59d16e251c45ef0be171519c48fd042c609 100644 --- "a/docs/zh/docs/20.09/docs/Releasenotes/\345\267\262\347\237\245\351\227\256\351\242\230.md" +++ "b/docs/zh/docs/20.09/docs/Releasenotes/\345\267\262\347\237\245\351\227\256\351\242\230.md" @@ -1,28 +1,61 @@ # 已知问题 - -

Issue

+ - - - - - - - - + + + + - + + - + +

Issue

Description

+

Description

I1BJTF

+

I1TPY4

[Kernel bug] The lscpu command on the ARM server cannot be used to display the CPU dominant frequency, and the CPU cache is incorrect.

+

x86/arm mariadb-server installation fails.

I1BWPD

+

I1TOV5

Failed to pull an image using the isula pull or curl pull command.

+

lm_sensors cannot be started by default, and systemd is in the degraded state.

I1BV56

+

I1TOCE

+

The kdump on an x86- or ARM-based physical machine fails to be started.

+

I1TZH1

+

The rule does not take effect when the destination port is 80 and the data packages from the source IP address of a host are added to the x86-based server.

+

I1T4O3

Delete redundant gpg sig file for shadow-4.6.

+

During x86 PXE installation, the %packages file in the .ks file is used to install minimal, @core, and @base. After the installation is successful, the startup is suspended.

+

I1T8JJ

+

The installation of the ARM-based freeRADIUS server fails.

I1BV38

+
+ +**Programming languages and compilers ** + + + + + + - - + +

Issue

+

Description

+

I1RUM6

The unbuffer command is unavailable.

+

Track the community to resolve the issue that the type of the file generated after the compilation of gcc -static-pie is incorrect.

I1BA9B

+
+ +**Virtualization and containers ** + + + + + + - + + + + - + +

Issue

+

Description

+

I1TB7N

The arping -w parameter is invalid.

+

PMU nmi watchdog does not support CPU hot-plug.

+

I1TXAU

+

The VM fails to be started when the VM CPU mode is configured with host-model.

+

I1U8BP

+

When openEuler is used to set trusted boot as an image, the VM cannot identify the TPM device.

I1AV3S

+
+ +**Kernel** + + + + + + - + + + + + + + + + - +

Issue

+

Description

+

I17YPQ

The oops error occurs when the latest LTP pty03 test case is executed.

+

The drive connected to the LSI SAS3408 RAID controller card cannot be identified during the installation.

I1JZHT

+

The Netdevsim is repeatedly loaded and uninstalled, causing the system to reset.

+

I1RUC8

+

The performance loss of vmalloc on x86-based servers is huge.

+

I1R86G

+

An error of pread is reported when openEuler performs a test on the open GaussDB, causing the return to -EIO.

+

I1SISM

+

The XFS drive with size=8192 cannot be mounted to the openEuler on the x86 platform.

+

I1AZ1I

+
+ +**Security ** + + + + + + - - + +

Issue

+

Description

+

I1TQ15

500 scheduled tasks are started. After 4 to 5 minutes, the tasks cannot be processed and the system stops responding.

+

An error is reported when the firewall-cmd --reload command is executed to add an IP address set that does not exist to the drop area as the source.

I1AH2C

+
+ +**Hardware and chips** ****** + + + + + + - + + - + +

Issue

+

Description

+

I1SY0K

The warning information captured when the Kata container fails to be started is insufficient for fault locating. More errors need to be printed.

+

The Raspberry Pi Wi-Fi is unavailable and the connection to the Wi-Fi network fails.

+

I1R4G1

+

The connection to the Raspberry Pi BT fails repeatedly.

I1AGXO

+
+ +**File system ** + + + + + + + + - + + - + +

Issue

+

Description

+

I1E0KN

+

A core dump occurs when a user creates and deletes folders concurrently in the XFS file system and uses the find command to query the folders.

+

I1MA88

In kata-runtime remote mode, the kata-runtime kill is not called when the isula rm -f command is executed. As a result, residual data exists.

+

The libguestfs uses the Gnulib code that has a vulnerability, causing a core dump.

+

I1T3GC

+

The memory allocation is reported to fail when the mounted drive letter is checked at the NFS client.

I1AF39

+
+ +**Network ** + + + + + + + + - + + - + +

Issue

+

Description

+

I1TO3R

+

An error occurs when the network-manager-appletda is invoked during installation and ipv4 is manually configured.

+

I1TYDG

The soft lockup is found when the open function is triggered in the ext4 file system.

+

The NetworkManager service cannot not be self-healed due to the D-Bus service exception.

+

I1AD7N

+

The IP address is lost when the network is restarted because the return value of the grep -L command in the network-scripts file is changed.

I1ADUD

+
+ +**System tools ** + + + + + + + - +

Issue

+

Description

+

I1U7RL

+

An error occurs during system-config-printer installation.

+

I1T8H4

Isulad breaks down when a pod is created using kubectl.

+

After the x86/ARM-based device is installed by default, the systemctl -all --failed command is executed and the tuned service fails to be started.
diff --git a/docs/en/docs/20.09/docs/Releasenotes/terms-of-use.md b/docs/en/docs/20.09/docs/Releasenotes/terms-of-use.md index dbbef6358b01550f1c2b03252c9b254e4682b953..1a7fbcac36f3cc1243592d9ce6a50f3704f9288f 100644 --- a/docs/en/docs/20.09/docs/Releasenotes/terms-of-use.md +++ b/docs/en/docs/20.09/docs/Releasenotes/terms-of-use.md @@ -1,14 +1,13 @@ # Terms of Use -**Copyright © Huawei Technologies Co., Ltd. 2020. All rights reserved.** +**Copyright © 2020 openEuler Community** Your replication, use, modification, and distribution of this document are governed by the Creative Commons License Attribution-ShareAlike 4.0 International Public License \(CC BY-SA 4.0\). You can visit [https://creativecommons.org/licenses/by-sa/4.0/](https://creativecommons.org/licenses/by-sa/4.0/) to view a human-readable summary of \(and not a substitute for\) CC BY-SA 4.0. For the complete CC BY-SA 4.0, visit [https://creativecommons.org/licenses/by-sa/4.0/legalcode](https://creativecommons.org/licenses/by-sa/4.0/legalcode). **Trademarks and Permissions** -openEuler is a trademark of Huawei Technologies Co., Ltd. All other trademarks and registered trademarks mentioned in this document are the property of their respective holders. +openEuler is the trademark of the openEuler community. All other trademarks and registered trademarks mentioned in this document are the property of their respective holders. **Disclaimer** This document is used only as a guide. Unless otherwise specified by applicable laws or agreed by both parties in written form, all statements, information, and recommendations in this document are provided "AS IS" without warranties, guarantees or representations of any kind, including but not limited to non-infringement, timeliness, and specific purposes. - diff --git a/docs/en/docs/20.09/docs/StratoVirt/Install_StratoVirt.md b/docs/en/docs/20.09/docs/StratoVirt/Install_StratoVirt.md new file mode 100644 index 0000000000000000000000000000000000000000..6b4772030cd4f760574e25e94e97d3795893631a --- /dev/null +++ b/docs/en/docs/20.09/docs/StratoVirt/Install_StratoVirt.md @@ -0,0 +1,39 @@ +# Installing StratoVirt + +[[toc]] + +## Software and Hardware Requirements + +### Minimum Hardware Requirements + +- Processor architecture: Only the AArch64 and x86_64 processor architectures are supported. AArch64 requires ARMv8 or a later version and supports virtualization extension. x86_64 supports VT-x. + +- 2-core CPU +- 4 GiB memory +- 16 GiB available disk space + +### Software Requirements + +Operating system: openEuler 20.09 or later + + + +## Installing Components + +To use StratoVirt virtualization, it is necessary to install StratoVirt. Before the installation, ensure that the openEuler yum source has been configured. + +1. Run the following command as user root to install the StratoVirt components: + + ``` + $ yum install stratovirt + ``` + + +2. Check whether the installation is successful. + + ``` + $ stratovirt -version + StratoVirt 0.1.0 + ``` + + diff --git a/docs/en/docs/20.09/docs/StratoVirt/Interconnect_isula.md b/docs/en/docs/20.09/docs/StratoVirt/Interconnect_isula.md new file mode 100644 index 0000000000000000000000000000000000000000..2dbc3d01bb4528d88470aaa16e0cadbeff2ba493 --- /dev/null +++ b/docs/en/docs/20.09/docs/StratoVirt/Interconnect_isula.md @@ -0,0 +1,40 @@ +# Interconnecting with the iSula Secure Container + +[[toc]] + +## Overview + +To provide a better isolation environment for containers and improve system security, it is necessary to connect Kata to StratoVirt in the iSula secure container scenario. + +## Interconnection with an iSula Secure Container + +**Prerequisites** + +iSulad and Kata containers have been installed. + +**Operations** + + + +The default path of the Kata configuration file is /usr/share/defaults/kata-containers/configuration.toml. + +1. Modify the configuration file to set the hypervisor type of the secure sandbox to stratovirt. + + ``` + [hypervisor.stratovirt] + ``` + +2. Set the execution file path of the secure sandbox to the absolute path of stratovirt.sh. The content of the stratovirt.sh script is as follows: + + ``` + #!/bin/bash + export QUANTVISOR_LOG_LEVEL=info # set log level + /usr/bin/stratovirt $@ + ``` + +3. Run iSulad to connect Kata to StratoVirt. + + ``` + $ isula run -tid --runtime=kata-runtime --name test busybox:latest sh + ``` + diff --git a/docs/en/docs/20.09/docs/StratoVirt/Manage_life_cycle.md b/docs/en/docs/20.09/docs/StratoVirt/Manage_life_cycle.md new file mode 100644 index 0000000000000000000000000000000000000000..b40f922d36a4d43c19746263685d4ece83186065 --- /dev/null +++ b/docs/en/docs/20.09/docs/StratoVirt/Manage_life_cycle.md @@ -0,0 +1,124 @@ +# Managing the VM Lifecycle + +[[toc]] + +## Overview + +This section describes how to use StratoVirt to manage the lifecycle of a VM, namely starting, pausing, resuming, and exiting a VM. + + + +## Creating and Starting a VM + +As described in the section "Configuring a VM", users can specify the VM configuration by using command line parameters or the JSON file, and run the stratovirt command on the host to create and start a VM. + +- Run the following command to create and start a VM: + +``` +$/path/to/stratovirt - [Parameter 1] [Parameter Option] - [Parameter 2] [Parameter Option]... +``` + + + +- Use the JSON file to provide the VM configuration. The command for creating and starting a VM is as follows: + +``` +$ /path/to/stratovirt \ + -config /path/to/json \ + -api-channel unix:/path/to/socket +``` + +Where, /path/to/json indicates the path of the JSON configuration file. / path/to/socket is the socket file specified by the user (for example, /tmp/stratovirt.socket). After the command is executed, the socket file is automatically created. Ensure that the socket file does not exist before executing the command, so that the VM can be started properly. + + + +> ![](./figures/en-05.png) +> +> After the VM is started, there are two NICs: eth0 and eth1. The two NICs are reserved for hot plugging: eth0 first, and then eth1. Currently, only two virtio-net NICs can be hot-plugged. + + + +## Connecting a VM + +StratoVirt uses QMP to manage VMs. To pause, resume, and exit a VM, connect it to StratoVirt through QMP first. + +Open a new CLI (CLI B) on the host and run the following command to perform the api-channel connection: + +``` +$ ncat -U /path/to/socket +``` + +After the connection is set up, a greeting message will be received from StratoVirt, as shown in the following figure. + +``` +{"QMP":{"version":{"qemu":{"micro":1,"minor":0,"major":4},"package":""},"capabilities":[]}} +``` + +Now, manage the VM by entering QMP commands in CLI B. + + + +> ![](./figures/en-05.png) +> +> QMP provides stop, cont, quit, and query-status to manage and query the VM status. +> +> All QMP commands for managing VMs are entered in CLI B. `<-` indicates the command input, and `->` indicates the QMP returned result. + + + + + +## Pausing a VM + +QMP provides the stop command for pausing a VM, that is, pausing all vCPUs of the VM. Command format: + +**{"execute":"stop"}** + +**Example:** + +Run the stop command to pause the VM. The command output is as follows: + +``` +<- {"execute":"stop"} +-> {"event":"STOP","data":{},"timestamp":{"seconds":1583908726,"microseconds":162739}} +-> {"return":{}} +``` + + + + + +## Resuming a VM + +QMP provides the cont command to resume a VM, that is, to resume all vCPUs of the VM. Command format: + +**{"execute":"cont"}** + +**Example:** + +Run the cont command to resume the VM. The command output is as follows: + +``` +<- {"execute":"cont"} +-> {"event":"RESUME","data":{},"timestamp":{"seconds":1583908853,"microseconds":411394}} +-> {"return":{}} +``` + + + + + +## Exiting a VM + +QMP provides the quit command to exit a VM, that is, to exit the StratoVirt process. Command format: + +**{"execute":"quit"}** + +**Example:** + +``` +<- {"execute":"quit"} +-> {"event":"SHUTDOWN","data":{"guest":false,"reason":"host-qmp-quit"},"timestamp":{"ds":1590563776,"microseconds":519808}} +-> {"return":{}} +``` + diff --git a/docs/en/docs/20.09/docs/StratoVirt/Manage_resource.md b/docs/en/docs/20.09/docs/StratoVirt/Manage_resource.md new file mode 100644 index 0000000000000000000000000000000000000000..0b4c2015c02854cb29084e95b9a73408685fb48c --- /dev/null +++ b/docs/en/docs/20.09/docs/StratoVirt/Manage_resource.md @@ -0,0 +1,114 @@ +#Managing VM resources + +[[toc]] + +## Overview + +This section describes how to use QMP commands to manage disks and NICs. + + + +> ![](./figures/en-05.png) +> +> StratoVirt uses QMP to manage VMs. Before using QMP to manage VM resources, use it to connect StratoVirt to the VM. For details, see "Managing the VM Life Cycle". + + + +## Hot-Pluggable Hard Disks + +StratoVirt supports adjusting the number of disks during VM running. That is, you can add or delete VM disks without interrupting services. + +### Hot Plugged-in Disk + +**Usage** + +``` +{"execute": "blockdev-add", "arguments": {"node-name": "drive-0", "file": {"driver": "file", "filename": "/path/to/block"}, "cache": {"direct": true}, "read-only": false}} +{"execute": "device_add", "arguments": {"id": "drive-0", "driver": "virtio-blk-mmio", "addr": "0x1"}} +``` + +**Parameter** + +- The value of node-name in blockdev-add must be the same as the value of id in device_add. They are both drive-0. + +- /path/to/block is the mirror path of the hot plugged-in disk. It cannot be the path of the disk image that boots the rootfs. +- For addr, 0x0 is mapped to vda of the VM, 0x1 is mapped to vdb, and so on. To be compatible with the QMP protocol, "addr" can be replaced by "lun", but lun=0 is mapped to the vdb of the client. Only six virtio-blk disks can be hot added. + +**Example** + +``` +<- {"execute": "blockdev-add", "arguments": {"node-name": "drive-0", "file": {"driver": "file", "filename": "/path/to/block"}, "cache": {"direct": true}, "read-only": false}} +-> {"return": {}} +<- {"execute": "device_add", "arguments": {"id": "drive-0", "driver": "virtio-blk-mmio", "addr": "0x1"}} +-> {"return": {}} +``` + + + +### Hot Plugged-out Disk + +**Usage** + +**{"execute": "device_del", "arguments": {"id":"drive-0"}}** + +**Parameter** + +id indicates the ID of the hot plugged-out disk. + +**Example** + +``` +<- {"execute": "device_del", "arguments": {"id": "drive-0"}} +-> {"event":"DEVICE_DELETED","data":{"device":"drive-0","path":"drive-0"},"timestamp":{"seconds":1598513162,"microseconds":367129}} +-> {"return": {}} +``` + + + +## Hot-Pluggable NIC + +StratoVirt allows users to adjust the number of NICs during VM running. That is, users can add or delete NICs for VMs without interrupting services. + +### Hot Plugged-in NIC + +**Usage** + +``` +{"execute":"netdev_add", "arguments":{"id":"net-0", "ifname":"tap0"}} +{"execute":"device_add", "arguments":{"id":"net-0", "driver":"virtio-net-mmio", "addr":"0x0"}} +``` + +**Parameter** + +- The ID in netdev_add must be the same as that in device_add. Ifname indicates the name of the TAP device. + +- For addr, 0x0 is mapped to eth0 of the VM, and 0x1 to eth1. Only two virtio-net NICs can be hot plugged in. + + +**Example** + +``` +<- {"execute":"netdev_add", "arguments":{"id":"net-0", "ifname":"tap0"}} +<- {"execute":"device_add", "arguments":{"id":"net-0", "driver":"virtio-net-mmio", "addr":"0x0"}} +``` + +Where, addr:0x0 corresponds to eth0 in the VM. + +### Hot Plugged-out NIC + +**Usage** + +**{"execute": "device_del", "arguments": {"id": "net-0"}}** + +**Parameter** + +id: specifies the NIC ID, for example, net-0. + +**Example** + +``` +<- {"execute": "device_del", "arguments": {"id": "net-0"}} +-> {"event":"DEVICE_DELETED","data":{"device":"net-0","path":"net-0"},"timestamp":{"seconds":1598513339,"microseconds":97310}} +-> {"return": {}} +``` + diff --git a/docs/en/docs/20.09/docs/StratoVirt/Prepare_env.md b/docs/en/docs/20.09/docs/StratoVirt/Prepare_env.md new file mode 100644 index 0000000000000000000000000000000000000000..dd1e7933d098523d0f1290c69efc1ec188c1ac72 --- /dev/null +++ b/docs/en/docs/20.09/docs/StratoVirt/Prepare_env.md @@ -0,0 +1,151 @@ +# Preparing the Environment + +[[toc]] + +## Usage + +- StratoVirt supports only Linux VMs that use the x86_64 or AArch64 processor architecture and start the VM with same architecture. +- StratoVirt can be compiled, commissioned, and deployed only on openEuler 20.09 and later versions. +- StratoVirt can run with non-root permissions. + +## Environment Requirements + +The following environment is required for running StratoVirt: + +- /dev/vhost-vsock device (for implementing the MMIO) +- Nmap tool +- Kernel image and rootfs image + + + +## Preparing Devices and Tools + +- StratoVirt needs to implement the MMIO device. Therefore, before running StratoVirt, ensure that the `/dev/vhost-vsock` device exists. + + Check whether the device exists. + + ``` + $ ls /dev/vhost-vsock + /dev/vhost-vsock + ``` + + If the device does not exist, run the following command to generate the /dev/vhost-vsock device: + + ``` + $ modprobe vhost_vsock + ``` + + + +- To use QMP commands, install the nmap tool. After configuring the yum source, run the following command to install the nmap tool: + + ``` + $ yum install nmap + ``` + +## Preparing Images + +### Creating the Kernel Image + +The StratoVirt of the current version supports only the PE kernel image of the x86_64 and AArch64 platforms. The kernel image in PE format can be generated by using the following method: + +1. Run the following command to obtain the kernel source code of the openEuler: + + ``` + $ git clone https://gitee.com/openeuler/kernel + $ cd kernel + ``` + +2. Run the following command to check and switch the kernel version to 4.19: + + ``` + $ git checkout kernel-4.19 + ``` + +3. Configure and compile the Linux kernel. It is better to use the recommended configuration file ([Obtain configuration file](https://gitee.com/openeuler/stratovirt/tree/master/docs/kernel_config)). Copy it to the kernel directory, and rename it as `.config`. You can also run the following command to configure the kernel as prompted: + + ``` + $ make menuconfig + ``` + +4. Run the following command to create and convert the kernel image to the PE format. The converted image is vmlinux.bin. + + ``` + $ make -j vmlinux && objcopy -O binary vmlinux vmlinux.bin + ``` + + After the compilation is complete, the kernel image vmlinux is generated in the current directory. + + + +## Creating the Rootfs Image + +The rootfs image is a file system image. When the StratoVirt is started, the ext4 image with init can be loaded. To create an ext4 rootfs image, perform the following steps: + +1. Prepare a file with a proper size (for example, create a file with the size of 10 GiB in /home). + + ``` + $ cd /home + $ dd if=/dev/zero of=./rootfs.ext4 bs=1G count=10 + ``` + +2. Create an empty ext4 file system on this file. + + ``` + $ mkfs.ext4 ./rootfs.ext4 + ``` + +3. Mount the file image. Create the /mnt/rootfs directory and mount rootfs.ext4 to the /mnt/rootfs directory as user root. + + ``` + $ mkdir /mnt/rootfs + $ cd /home + $ sudo mount ./rootfs.ext4 /mnt/rootfs && cd /mnt/rootfs + ``` + +4. Obtain the latest alpine-mini rootfs of the corresponding processor architecture. + + - If the AArch64 processor architecture is used, run the following command: + + ``` + $ wget http://dl-cdn.alpinelinux.org/alpine/latest-stable/releases/aarch64/alpine-minirootfs-3.12.0-aarch64.tar.gz + $ tar -zxvf alpine-minirootfs-3.12.0-aarch64.tar.gz + $ rm alpine-minirootfs-3.12.0-aarch64.tar.gz + ``` + + + + - For the x86_64 processor architecture, run the following command: + + ``` + $ wget http://dl-cdn.alpinelinux.org/alpine/latest-stable/releases/x86_64/alpine-minirootfs-3.12.0-x86_64.tar.gz + $ tar -zxvf alpine-minirootfs-3.12.0-x86_64.tar.gz + $ rm alpine-minirootfs-3.12.0-x86_64.tar.gz + ``` + + + +5. Run the following command to create a simple /sbin/init for the ext4 file image: + + ``` + $ rm sbin/init && touch sbin/init && cat > sbin/init < { "return": { "running": true,"singlestep": false,"status": "running" } +``` + + + +## Querying Topology Information + +Run the query-cpus command to query the topology of all CPUs. + +- Usage: + +**{ "execute": "query-cpus" }** + +- Example: + +``` +<- { "execute": "query-cpus" } +-> {"return":[{"CPU":0,"arch":"x86","current":true,"halted":false,"props":{"core-id":0,"socket-id":0,"thread-id":0},"qom_path":"/machine/unattached/device[0]","thread_id":8439},{"CPU":1,"arch":"x86","current":true,"halted":false,"props":{"core-id":0,"socket-id":1,"thread-id":0},"qom_path":"/machine/unattached/device[1]","thread_id":8440}]} +``` + +## Querying vCPU Online Status + +Run the query-hotpluggable-cpus command to query the online or offline status of all vCPUs. + +- Usage: + +**{ "execute": "query-hotpluggable-cpus" }** + +- Example: + +``` +<- { "execute": "query-hotpluggable-cpus" } +-> {"return":[{"props":{"core-id":0,"socket-id":0,"thread-id":0},"qom-path":"/machine/unattached/device[0]","type":"host-x86-cpu","vcpus-count":1},{"props":{"core-id":0,"socket-id":1,"thread-id":0},"qom-path":"/machine/unattached/device[1]","type":"host-x86-cpu","vcpus-count":1}]} +``` + +Where, online vCPUs have the `qom-path` item, while offline vCPUs do not. diff --git a/docs/en/docs/20.09/docs/StratoVirt/StratoVirt_Intoduction.md b/docs/en/docs/20.09/docs/StratoVirt/StratoVirt_Intoduction.md new file mode 100644 index 0000000000000000000000000000000000000000..4e55c8bd86b2abff2b20d4b5d4160f21a9c6b73f --- /dev/null +++ b/docs/en/docs/20.09/docs/StratoVirt/StratoVirt_Intoduction.md @@ -0,0 +1,27 @@ +# Introduction to StratoVirt + +[[toc]] + +## Overview + +In the field of data center, virtualization is an important method for resource isolation, providing a secure virtual runtime environment with multiple granularities. However, traditional virtualization software such as QEMU has a large amount of code and frequent CVE security vulnerabilities. The industry has gradually evolved the trend of using the Rust language to implement microVM. In the future, general virtualization technologies will feature being secure, lightweight, enjoying high-performance, low-loss, flexible component splitting, and applying to all scenarios (data centers, terminals, and edge devices). + +StratoVirt is a lightweight virtualization solution implemented by Rust. It simplifies the device model, optimizes the running performance, and provides a secure sandbox running environment with security isolation and excellent performance for containers. + + + +## Architecture Description + +The StratoVirt core architecture is divided into three layers from top to bottom: + +- OCI: compatible with the QEMU Machine Protocol (QMP), which has complete OCI compatibility capabilities. +- BootLoader: discards the traditional BIOS+GRUB boot mode and implements a lighter and faster bootloader. +- MicroVM: virtualization layer, which fully leverages the capability of software and hardware collaboration to simplify the device model and the capability of low-latency resource scaling. + +The overall architecture is shown in **Figure 1**. + +**Figure 1** Overall architecture of StratoVirt + +![](./figures/arc.png) + + diff --git a/docs/en/docs/20.09/docs/StratoVirt/StratoVrit_guidence.md b/docs/en/docs/20.09/docs/StratoVirt/StratoVrit_guidence.md new file mode 100644 index 0000000000000000000000000000000000000000..8420ae5b97ef7a27fcebff535caf0d76bff24428 --- /dev/null +++ b/docs/en/docs/20.09/docs/StratoVirt/StratoVrit_guidence.md @@ -0,0 +1,4 @@ +# StratoVirt Virtualization User Guide + +This document describes Stratovirt virtualization, providing instructions on how to install Stratovirt based on openEuler and how to use Stratovirt virtualization. The purpose is to help users learn about Stratovirt and guide users and administrators to install and use Stratovirt. + diff --git a/docs/en/docs/20.09/docs/StratoVirt/VM_configuration.md b/docs/en/docs/20.09/docs/StratoVirt/VM_configuration.md new file mode 100644 index 0000000000000000000000000000000000000000..d876c4739268d8267efdc92f4e143ca5daf5b22c --- /dev/null +++ b/docs/en/docs/20.09/docs/StratoVirt/VM_configuration.md @@ -0,0 +1,235 @@ +# Configuring a VM + +## Overview + +Different from Libvirt that uses XML files to configure VMs, StratoVirt can use command line parameters or the JSON file to configure the VM CPU, memory, and disk information. This section describes the two configuration methods. + +> ![](./figures/en-05.png) +> +> If both methods can be used, incline to the command line configuration. +> +> In this document, /path/to/socket is the socket file in the user-defined path. + + + + + +## Specifications + +- Number of VM CPUs: [1,254] +- VM memory size: [128MiB,512GiB] +- Number of VM disks (including hot swap disks): [0,6] +- Number of VM NICs (including hot swap NICs): [0,2] +- The VM console device supports only single way connection. +- On the x86_64 platform, a maximum of two other devices except disks and NICs can be configured. On the AArch64 platform, the maximum of other devices is 12, also excluding disks and NICs. + +## Minimum Configuration + +The minimum configuration of the StratoVirt is as follows: + +- There is a Linux kernel file in PE format. +- Set the rootfs image as the virtio-blk device and add it to kernel parameters. +- Use api-channel to control StratoVirt. +- If you want to use ttyS0 for login, add a serial port to the startup command line and add ttyS0 to kernel parameters. + + + +## Command Line Configuration + +**Overview** + +Command line configuration directly specifies the VM configuration content using command line parameters. + +**Command Format** + +The format of the command configured by running the cmdline command is as follows: + +**$ /path/to/stratovirt** *-[Parameter 1] [Parameter Option] -[Parameter 2] [Parameter Option] ...* + +**Usage** + +1. To ensure that the socket required by api-channel can be created, run the following command to clear the environment: + + ``` + $rm [parameter] [user-defined socket file path] + ``` + + + +2. Run the cmdline command. + + ``` + $ /path/to/stratovirt -[Parameter 1] [Parameter Option] -[Parameter 2] [Parameter Option] ... + ``` + + + +**Parameter Description** + +The following table lists the parameters of the cmdline command. + +**Table 1** Description of command line configuration parameters + +| Parameter | Value | Description | +| ---------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | +| -name | *VMName* | Configures the VM name (a string of 1 to 255 characters).| +| -kernel | /path/to/vmlinux.bin | Configures the kernel image.| +| -append | console=ttyS0 root=/dev/vda reboot=k panic=1 | Configures kernel command line parameters.| +| -initrd | /path/to/initrd.img | Configures the initrd file.| +| -smp | [cpus=] Number of CPUs | Configures the number of CPUs. The value range is [1,254].| +| -m | Byte/MiB/GiB | Configures the memory size. The value range is [128MiB,512GiB]. | +| -drive | id=rootfs,file=/path/to/rootfs[,readonly=false,direct=true,serial=serial_num] | Configures the virtio-blk device.| +| -netdev | id=iface_id,netdev=tap0[,mac=mac_address] | Configures the virtio-net device.| +| -chardev | id=console_id,path=/path/to/socket | Configures virtio-console. Ensure that the socket file does not exist before running the command.| +| -device | vsock,id=vsock_id,guest-cid=3 | Configures vhost-vsock.| +| -api-channel | unix:/path/to/socket | Configures api-channel. Before running this command, ensure that the socket file does not exist.| +| -serial | stdio | Configures a serial port device.| +| -D | /path/to/logfile | Configures log files.| +| -pidfile | /path/to/pidfile | Configures the PID file. This parameter must be used together with -daemonize.| +| -disable-seccomp | N/A | Disables the Seccomp, which is enabled by default.| +| -omit_vm_memory | N/A | Do not dump the VM memory when the process enters the panic state.| +| -daemonize | N/A | Enables the daemon process.| + + + +**Example** + +1. Delete the socket file to ensure that the api-channel can be created. + + ``` + $ rm -f /tmp/stratovirt.socket + ``` + + + +2. Run StratoVirt. + + ``` + $ /path/to/stratovirt \ + -kernel /path/to/vmlinux.bin \ + -append console=ttyS0 root=/dev/vda reboot=k panic=1 \ + -drive file=/home/rootfs.ext4,id=rootfs,readonly=false \ + -api-channel unix:/tmp/stratovirt.socket \ + -serial stdio + ``` + + After the running is successful, the VM is created and started based on the specified configuration parameters. + + + +## JSON Configuration + + + +**Overview** + +Configuration using the JSON file indicates that when running StratoVirt to create a VM, the system reads the specified JSON file that contains the VM configuration. + +**Command Format** + +The format of the command for configuring a VM using the JSON file is as follows. In this command, /path/to/json indicates the path of the corresponding file. + +**$ /path/to/stratovirt -config** */path/to/json -[Parameter] [Parameter Option]* + +**Usage** + +1. Create a JSON file and write the VM configuration to the file. + +2. Run the StratoVirt command to create a VM. + + ``` + $ /path/to/stratovirt -config /path/to/json - [Parameter] [Parameter Option] + ``` + +**Parameter Description** + +The following table describes the configurable parameters in the JSON file. + +**Table 2** Parameters in the configuration file + +| Parameter | Value | Description | +| -------------- | ------------------------------------------------------------ | ---------------------------------------------------- | +| boot-source | "kernel_image_path": "/path/to/vmlinux.bin","boot_args": "console=ttyS0 reboot=k panic=1 pci=off tsc=reliable ipv6.disable=1 root=/dev/vda quiet","initrd_fs_path": "/path/to/initrd.img" | Configures the kernel image and kernel parameters. The `initrd_fs_path` parameter is optional. | +| machine-config | "name": "abc","vcpu_count": 4,"mem_size": 805306368,"omit_vm_memory": true | Configures the virtual CPU and memory size. The `omit_vm_memory` parameter is optional. | +| drive | "drive_id": "rootfs","path_on_host": "/path/to/rootfs.ext4","read_only": false,"direct": true,"serial_num": "xxxxx" | Configures the virtio-blk disk. The `serial_num` parameter is optional. | +| net | "iface_id": "net0","host_dev_name": "tap0","mac": "xx:xx:xx:xx:xx:xx" | Configures the virtio-net NIC. The `mac` parameter is optional. | +| console | "console_id": "charconsole0","socket_path": "/path/to/socket" | Configures the virtio-console serial port. Before running the serial port, ensure that the socket file does not exist. | +| vsock | "vsock_id": "vsock0","guest_cid": 3 | Configures the virtio-vsock device. | +| serial | "stdio": true | Configures a serial port device.| + + + +The following table lists the parameters running in JSON. + +**Table 3** Parameters running in JSON + +| Parameter | Value | Description | +| ---------------- | -------------------- | ------------------------------------------------------------ | +| -config | /path/to/json | Configures the file path.| +| -api-channel | unix:/path/to/socket | Configures api-channel. Before running this command, ensure that the socket file does not exist. | +| -D | /path/to/logfile | Configures log files.| +| -pidfile | /path/to/pidfile | Configures the PID file, which must be used together with daemonize. Before running the command, make sure that the PID file does not exist. | +| -disable-seccomp | N/A | Disables the Seccomp, which is enabled by default. | +| -daemonize | N/A | Enables the daemon process.| + + + +**Example** + +1. Create a JSON file, for example, /home/config.json. The file content is as follows: + +``` +{ + "boot-source": { + "kernel_image_path": "/path/to/vmlinux.bin", + "boot_args": "console=ttyS0 reboot=k panic=1 pci=off tsc=reliable ipv6.disable=1 root=/dev/vda quiet" + }, + "machine-config": { + "name": "abc", + "vcpu_count": 2, + "mem_size": 268435456, + "omit_vm_memory": false + }, + "drive": [ + { + "drive_id": "rootfs", + "path_on_host": "/path/to/rootfs.ext4", + "direct": true, + "read_only": false, + "serial_num": "abcd" + } + ], + "net": [ + { + "iface_id": "net0", + "host_dev_name": "tap0", + "mac": "0e:90:df:9f:a8:88" + } + ], + "console": { + "console_id": "charconsole0", + "socket_path": "/path/to/console.socket" + }, + "serial": { + "stdio": true + }, + "vsock": { + "vsock_id": "vsock-123321132", + "guest_cid": 4 + } +} + +``` + + + +2. Run StratoVirt to read the JSON file and create and start the VM. + +``` +$ /path/to/stratovirt \ + -config /home/config.json \ + -api-channel unix:/tmp/stratovirt.socket +``` + +Successful execution of the command indicates that the VM is successfully created and started. + diff --git a/docs/en/docs/20.09/docs/StratoVirt/figures/arc.png b/docs/en/docs/20.09/docs/StratoVirt/figures/arc.png new file mode 100644 index 0000000000000000000000000000000000000000..baf5526d077a452c9d8a18af38638c8db9150d27 Binary files /dev/null and b/docs/en/docs/20.09/docs/StratoVirt/figures/arc.png differ diff --git a/docs/en/docs/20.09/docs/StratoVirt/figures/en-05.png b/docs/en/docs/20.09/docs/StratoVirt/figures/en-05.png new file mode 100644 index 0000000000000000000000000000000000000000..ad5ed3f7beeb01e6a48707c4806606b41d687e22 Binary files /dev/null and b/docs/en/docs/20.09/docs/StratoVirt/figures/en-05.png differ diff --git a/docs/en/docs/20.09/docs/Virtualization/best-practices.md b/docs/en/docs/20.09/docs/Virtualization/best-practices.md index 94069b02437a6829e448580b20fe05cc886eaeb3..f25109385623c66c030c95efcea6e3785e306387 100644 --- a/docs/en/docs/20.09/docs/Virtualization/best-practices.md +++ b/docs/en/docs/20.09/docs/Virtualization/best-practices.md @@ -1,18 +1,6 @@ # Best Practices -- [Best Practices](#best-practices) - - [Performance Best Practices](#performance-best-practices) - - [Halt-Polling](#halt-polling) - - [I/O Thread Configuration](#i-o-thread-configuration) - - [Raw Device Mapping](#raw-device-mapping) - - [kworker Isolation and Binding](#kworker-isolation-and-binding) - - [HugePage Memory](#hugepage-memory) - - [PV-qspinlock](#pv-qspinlock) - - [Security Best Practices](#security-best-practices) - - [Libvirt Authentication](#libvirt-authentication) - - [qemu-ga](#qemu-ga) - - [sVirt Protection](#svirt-protection) - - [VM Trusted Boot](#VM-Trusted-Boot) +[[tod]] ## Performance Best Practices @@ -238,6 +226,73 @@ Modify the /boot/efi/EFI/openEuler/grub.cfg configuration file of the VM, add ar >![](./public_sys-resources/icon-note.gif) **Note:** >PV-qspinlock is supported only when the operating systems of the host machine and VM are both openEuler-20.09 or later and the VM kernel compilation option CONFIG_PARAVIRT_SPINLOCKS is set to y (default value for openEuler). +### Guest-Idle-Haltpoll + +#### Overview + +To ensure fairness and reduce power consumption, when the vCPU of the VM is idle, the VM executes the WFx/HLT instruction to exit to the host machine and triggers context switchover. The host machine determines whether to schedule other processes or vCPUs on the physical CPU or enter the energy saving mode. However, overheads of switching between a virtual machine and a host machine, additional context switching, and IPI wakeup are relatively high, and this problem is particularly prominent in services where sleep and wakeup are frequently performed. The Guest-Idle-Haltpoll technology indicates that when the vCPU of a VM is idle, the WFx/HLT is not executed immediately and VM-exit occurs. Instead, polling is performed on the VM for a period of time. During this period, the tasks of other vCPUs that share the LLC on the vCPU are woken up without sending IPI interrupts. This reduces the overhead of sending and receiving IPI interrupts and the overhead of VM-exit, thereby reducing the task wakeup latency. + +>![](public_sys-resources/icon-note.gif) **Note:** + The execution of the idle-haltpoll command by the vCPU on the VM increases the CPU overhead of the vCPU on the host machine. Therefore, it is recommended that the vCPU exclusively occupy physical cores on the host machine when this feature is enabled. + +#### Procedure + +The Guest-Idle-Haltpoll feature is disabled by default. The following describes how to enable this feature. + +1. Enable the Guest-Idle-Haltpoll feature. + - If the processor architecture of the host machine is x86, you can configure hint-dedicated in the XML file of the VM on the host machine to enable this feature. In this way, the status that the vCPU exclusively occupies the physical core can be transferred to the VM through the VM XML configuration. The host machine ensures the status of the physical core exclusively occupied by the vCPU. + + ``` + + ... + + + ... + + + + ... + + ``` + + Alternatively, set cpuidle\_haltpoll.force to Y in the kernel startup parameters of the VM to forcibly enable the function. This method does not require the host machine to configure the vCPU to exclusively occupy the physical core. + ``` + cpuidle_haltpoll.force=Y + ``` + + - If the processor architecture of the host machine is AArch64, this feature can be enabled only by configuring cpuidle\_haltpoll.force=Y haltpoll.enable=Y in the VM kernel startup parameters. + + ``` + cpuidle_haltpoll.force=Y haltpoll.enable=Y + ``` + +2. Check whether the Guest-Idle-Haltpoll feature takes effect. Run the following command on the VM. If haltpoll is returned, the feature has taken effect. + + ``` + # cat /sys/devices/system/cpu/cpuidle/current_driver + ``` + +3. (Optional) Set the Guest-Idle-Haltpoll parameter. + + The following configuration files are provided in the /sys/module/haltpoll/parameters/ directory of the VM. You can adjust the configuration parameters based on service characteristics. + + - guest\_halt\_poll\_ns: a global parameter that specifies the maximum polling duration after the vCPU is idle. The default value is 200000 (unit: ns). + - guest\_halt\_poll\_shrink: a divisor that is used to shrink the current vCPU guest\_halt\_poll\_ns when the wakeup event occurs after the global guest\_halt\_poll\_ns time. The default value is 2. + - guest\_halt\_poll\_grow: a multiplier that is used to extend the current vCPU guest\_halt\_poll\_ns when the wakeup event occurs after the current vCPU guest\_halt\_poll\_ns and before the global guest\_halt\_poll\_ns. The default value is 2. + - guest\_halt\_poll\_grow\_start: When the system is idle, the guest\_halt\_poll\_ns of each vCPU reaches 0. This parameter is used to set the initial value of the current vCPU guest\_halt\_poll\_ns to facilitate scaling in and scaling out of the vCPU polling duration. The default value is 50000 (unit: ns). + - guest\_halt\_poll\_allow\_shrink: a switch that is used to enable vCPU guest\_halt\_poll\_ns scale-in. The default value is Y. (Y indicates enabling the scale-in; N indicates disabling the scale-in.) + + You can run the following command as the user root to change the parameter values: In the preceding command, _value_ indicates the parameter value to be set, and _configFile_ indicates the corresponding configuration file. + + ``` + # echo value > /sys/module/haltpoll/parameters/configFile + ``` + + For example, to set the global guest\_halt\_poll\_ns to 200000 ns, run the following command: + + ``` + # echo 200000 > /sys/module/haltpoll/parameters/guest_halt_poll_ns + ``` ## security Best Practices diff --git a/docs/en/docs/20.09_LTS/docs/Virtualization/figures/CertEnrollP1.png b/docs/en/docs/20.09/docs/Virtualization/figures/CertEnrollP1.png similarity index 100% rename from docs/en/docs/20.09_LTS/docs/Virtualization/figures/CertEnrollP1.png rename to docs/en/docs/20.09/docs/Virtualization/figures/CertEnrollP1.png diff --git a/docs/en/docs/20.09_LTS/docs/Virtualization/figures/CertEnrollP2.png b/docs/en/docs/20.09/docs/Virtualization/figures/CertEnrollP2.png similarity index 100% rename from docs/en/docs/20.09_LTS/docs/Virtualization/figures/CertEnrollP2.png rename to docs/en/docs/20.09/docs/Virtualization/figures/CertEnrollP2.png diff --git a/docs/en/docs/20.09_LTS/docs/Virtualization/figures/CertEnrollP3.png b/docs/en/docs/20.09/docs/Virtualization/figures/CertEnrollP3.png similarity index 100% rename from docs/en/docs/20.09_LTS/docs/Virtualization/figures/CertEnrollP3.png rename to docs/en/docs/20.09/docs/Virtualization/figures/CertEnrollP3.png diff --git a/docs/en/docs/20.09_LTS/docs/Virtualization/figures/CertEnrollP4.png b/docs/en/docs/20.09/docs/Virtualization/figures/CertEnrollP4.png similarity index 100% rename from docs/en/docs/20.09_LTS/docs/Virtualization/figures/CertEnrollP4.png rename to docs/en/docs/20.09/docs/Virtualization/figures/CertEnrollP4.png diff --git a/docs/en/docs/20.09_LTS/docs/Virtualization/figures/CertEnrollP5.png b/docs/en/docs/20.09/docs/Virtualization/figures/CertEnrollP5.png similarity index 100% rename from docs/en/docs/20.09_LTS/docs/Virtualization/figures/CertEnrollP5.png rename to docs/en/docs/20.09/docs/Virtualization/figures/CertEnrollP5.png diff --git a/docs/en/docs/20.09_LTS/docs/Virtualization/figures/CertEnrollP6.png b/docs/en/docs/20.09/docs/Virtualization/figures/CertEnrollP6.png similarity index 100% rename from docs/en/docs/20.09_LTS/docs/Virtualization/figures/CertEnrollP6.png rename to docs/en/docs/20.09/docs/Virtualization/figures/CertEnrollP6.png diff --git a/docs/en/docs/20.09_LTS/docs/Virtualization/figures/CertEnrollP7.png b/docs/en/docs/20.09/docs/Virtualization/figures/CertEnrollP7.png similarity index 100% rename from docs/en/docs/20.09_LTS/docs/Virtualization/figures/CertEnrollP7.png rename to docs/en/docs/20.09/docs/Virtualization/figures/CertEnrollP7.png diff --git a/docs/en/docs/20.09_LTS/docs/Virtualization/figures/CertEnrollP8.png b/docs/en/docs/20.09/docs/Virtualization/figures/CertEnrollP8.png similarity index 100% rename from docs/en/docs/20.09_LTS/docs/Virtualization/figures/CertEnrollP8.png rename to docs/en/docs/20.09/docs/Virtualization/figures/CertEnrollP8.png diff --git a/docs/en/docs/20.09_LTS/docs/Virtualization/figures/OSBootFlow.png b/docs/en/docs/20.09/docs/Virtualization/figures/OSBootFlow.png similarity index 100% rename from docs/en/docs/20.09_LTS/docs/Virtualization/figures/OSBootFlow.png rename to docs/en/docs/20.09/docs/Virtualization/figures/OSBootFlow.png diff --git a/docs/en/docs/20.09_LTS/docs/Virtualization/figures/SecureBootFlow.png b/docs/en/docs/20.09/docs/Virtualization/figures/SecureBootFlow.png similarity index 100% rename from docs/en/docs/20.09_LTS/docs/Virtualization/figures/SecureBootFlow.png rename to docs/en/docs/20.09/docs/Virtualization/figures/SecureBootFlow.png diff --git a/docs/en/docs/20.09/docs/Virtualization/managing-vms.md b/docs/en/docs/20.09/docs/Virtualization/managing-vms.md index 5a5b1ae8995c833cc8193744388426d4c9586892..743a5cce6207fa7326cb0716d235775b778a35da 100644 --- a/docs/en/docs/20.09/docs/Virtualization/managing-vms.md +++ b/docs/en/docs/20.09/docs/Virtualization/managing-vms.md @@ -707,7 +707,7 @@ The components in the edk rpm package are installed in the /usr/share/edk2/aarch ``` -In the preceding configuration, /usr/share/edk2/aarch64/QEMU_EFI-pflash.raw indicates the path of UEFI BIOS image, /path/to/QEMU-VARS.fd indicates the path of nvram image template. /usr/share/edk2/aarch64/vars-template-pflash.raw indicates the nvram image template path, and /path/to/QEMU-VARS.fd indicates the nvram image file path of the current virtual machine, which is used to save the environment variables in the UEFI BIOS system. +In the preceding configuration, /usr/share/edk2/aarch64/QEMU_EFI-pflash.raw indicates the path of the UEFI BIOS image. /usr/share/edk2/aarch64/vars-template-pflash.raw is the path of the NVRAM image template, and /path/to/QEMU-VARS.fd is the path of the NVRAM image file of the current VM, which is used to store environment variables in the UEFI BIOS. ##### Importing Certificate @@ -779,7 +779,7 @@ Select the PK certificate to be imported in the disk directory. ![](./figures/CertEnrollP8.png) -After the certificate is imported, the UEFI BIOS writes the certificate information and secure boot attributes into the nvram configuration file /path/to/QEMU-VARS.fd. The next time the virtual machine starts up, it will read the configuration and initialize the certificate information and secure boot attributes from the file /path/to/QEMU-VARS.fd, importing the certificate and enable secure boot automatically. Similarly, we can use the file /path/to/QEMU-VARS.fd as a UEFI BIOS boot configuration template file for other same configured VMs, and make the other VMs boot with the certificate automatically imported and the secure boot option enabled by modifying the nvram template field with the following VM xml configuration changes. +After the certificate is imported, the UEFI BIOS writes the certificate information and secure boot attributes to the NVRAM configuration file /path/to/QEMU-VARS.fd. Upon the next startup, the VM reads related configurations from the /path/to/QEMU-VARS.fd file, initializes certificate information and secure boot attributes, automatically imports the certificate, and enables secure boot. Similarly, you can use /path/to/QEMU-VARS.fd as the UEFI BIOS boot configuration template file of other VMs with the same configuration. Modify the nvram template field so that the certificate is automatically imported and the secure boot option is enabled when other VMs are started. The VM XML configuration is modified as follows: ``` diff --git a/docs/en/docs/20.09/docs/Virtualization/system-resource-management.md b/docs/en/docs/20.09/docs/Virtualization/system-resource-management.md index 456489f7cb821054805c891b194b21f35ad5d67b..85b57feff631d08eef959895573803055e7af15a 100644 --- a/docs/en/docs/20.09/docs/Virtualization/system-resource-management.md +++ b/docs/en/docs/20.09/docs/Virtualization/system-resource-management.md @@ -1,5 +1,8 @@ # system Resource Management +[[tod]] + + The **libvirt** command manages VM system resources, such as vCPU and virtual memory resources. Before you start: @@ -7,19 +10,6 @@ Before you start: - Ensure that the libvirtd daemon is running on the host. - Run the **virsh list --all** command to check that the VM has been defined. -- [System Resource Management](#system-resource-management) - - [Managing vCPU](#managing-vcpu) - - [CPU Shares](#cpu-shares) - - [Binding the QEMU Process to a Physical CPU](#binding-the-qemu-process-to-a-physical-cpu) - - [Adjusting the vCPU Binding Relationship](#adjusting-the-vcpu-binding-relationship) - - [CPU Hot Add](#cpu-hot-add) - - [Managing Virtual Memory](#managing-virtual-memory) - - [Introduction to NUMA](#introduction-to-numa) - - [Configuring Host NUMA](#configuring-host-numa) - - [Configuring Guest NUMA](#configuring-guest-numa) - - [Memory Hot Add](#memory-hot-add) - - ## Managing vCPU diff --git a/docs/en/docs/20.09/docs/Virtualization/tool-guide.md b/docs/en/docs/20.09/docs/Virtualization/tool-guide.md new file mode 100644 index 0000000000000000000000000000000000000000..5deedcda7058549bdc9d8575394aa740d967d8a9 --- /dev/null +++ b/docs/en/docs/20.09/docs/Virtualization/tool-guide.md @@ -0,0 +1,140 @@ +# Tool Guide + +- [vmtop](#vmtop) + +## vmtop + +### Overview +vmtop is a user-mode tool running on the host machine. You can use the vmtop tool to dynamically view the usage of VM resources in real time, such as CPU usage, memory usage, and the number of vCPU traps. Therefore, the vmtop tool can be used to locate virtualization problems and optimize performance. + +The vmtop monitoring items are as follows (sampling difference: difference between two data obtained at a specified interval): +- VM/task-name: VM/Process name +- DID: VM ID +- PID: PID of the qemu process of the VM +- %CPU: CPU usage of a process +- EXThvc: Number of hvc-exits (sampling difference) +- EXTwfe: Number of wfe-exits (sampling difference) +- EXTwfi: Number of wfi-exits (sampling difference) +- EXTmmioU: Number of mmioU-exits (sampling difference) +- EXTmmioK: Number of mmioK-exits (sampling difference) +- EXTfp: Number of fp-exits (sampling difference) +- EXTirq: Number of irq-exits (sampling difference) +- EXTsys64: Number of sys64 exits (sampling difference) +- EXTmabt: Number of mem abort exits (sampling difference) +- EXTsum: Total number of KVM exits (sampling difference) +- S: Process status +- P: Physical CPU usage of a process +- %ST: Ratio of the preemption time to the CPU running time (KVM data) +- %GUE: Ratio of the VM internal occupation time to the CPU running time (KVM data) +- %HYP: Virtualization overhead ratio (KVM data) + +### Usage +vmtop is a command line tool. You can directly run the vmtop in command line mode. +In addition, the vmtop tool provides different options for querying different information. + +#### Syntax +```sh +vmtop [option] +``` + +#### Option Description +- -d: sets the refresh interval, in seconds. +- -H: displays the VM thread information. +- -n: sets the number of refresh times and exits after the refresh is complete. +- -b: displays Batch mode, which can be used to redirect to a file. +- -h: displays help information. +- -v: displays versions. + +#### Keyboard Shortcut +Shortcut key used when the vmtop is running. +- H: displays or stops the VM thread information. The information is displayed by default. +- up/down: moves the VM list upwards or downwards. +- left/right: moves the cursor leftwards or rightwards to display the columns that are hidden due to the screen width. +- f: enters the editing mode of a monitoring item and selects the monitoring item to be enabled. +- q: exits the vmtop process. + +### Example +Run the vmtop command on the host. +```sh +vmtop +``` +The command output is as follows: +```sh +vmtop - 2020-09-14 09:54:48 - 1.0 +Domains: 1 running + + DID VM/task-name PID %CPU EXThvc EXTwfe EXTwfi EXTmmioU EXTmmioK EXTfp EXTirq EXTsys64 EXTmabt EXTsum S P %ST %GUE %HYP + 2 example 4054916 13.0 0 0 1206 10 0 144 62 174 0 1452 S 106 0.0 99.7 16.0 +``` +As shown in the output, there is only one VM named "example" on the host. The ID is 2. The CPU usage is 13.0%. The total number of traps within one second is 1452. The physical CPU occupied by the VM process is CPU 106. The ratio of the VM internal occupation time to the CPU running time is 99.7%. + +1. Display VM thread information. +Press H to display the thread information. +```sh +vmtop - 2020-09-14 10:11:27 - 1.0 +Domains: 1 running + + DID VM/task-name PID %CPU EXThvc EXTwfe EXTwfi EXTmmioU EXTmmioK EXTfp EXTirq EXTsys64 EXTmabt EXTsum S P %ST %GUE %HYP + 2 example 4054916 13.0 0 0 1191 17 4 120 76 147 0 1435 S 119 0.0 123.7 4.0 + |_ qemu-kvm 4054916 0.0 0 0 0 0 0 0 0 0 0 0 S 119 0.0 0.0 0.0 + |_ qemu-kvm 4054928 0.0 0 0 0 0 0 0 0 0 0 0 S 119 0.0 0.0 0.0 + |_ signalfd_com 4054929 0.0 0 0 0 0 0 0 0 0 0 0 S 120 0.0 0.0 0.0 + |_ IO mon_iothr 4054932 0.0 0 0 0 0 0 0 0 0 0 0 S 117 0.0 0.0 0.0 + |_ CPU 0/KVM 4054933 3.0 0 0 280 6 4 28 19 41 0 350 S 105 0.0 27.9 0.0 + |_ CPU 1/KVM 4054934 3.0 0 0 260 0 0 16 12 36 0 308 S 31 0.0 20.0 0.0 + |_ CPU 2/KVM 4054935 3.0 0 0 341 0 0 44 20 26 0 387 R 108 0.0 27.9 4.0 + |_ CPU 3/KVM 4054936 5.0 0 0 310 11 0 32 25 44 0 390 S 103 0.0 47.9 0.0 + |_ memory_lock 4054940 0.0 0 0 0 0 0 0 0 0 0 0 S 126 0.0 0.0 0.0 + |_ vnc_worker 4054944 0.0 0 0 0 0 0 0 0 0 0 0 S 118 0.0 0.0 0.0 + |_ worker 4143738 0.0 0 0 0 0 0 0 0 0 0 0 S 120 0.0 0.0 0.0 +``` +The example VM has 11 threads, including the vCPU thread, vnc_worker, and IO mon_iotreads. Each thread also displays detailed CPU usage and trap information. + +2. Select the monitoring item. +Enter f to edit the monitoring item. +```sh +field filter - select which field to be showed +Use up/down to navigate, use space to set whether chosen filed to be showed +'q' to quit to normal display + + * DID + * VM/task-name + * PID + * %CPU + * EXThvc + * EXTwfe + * EXTwfi + * EXTmmioU + * EXTmmioK + * EXTfp + * EXTirq + * EXTsys64 + * EXTmabt + * EXTsum + * S + * P + * %ST + * %GUE + * %HYP +``` +By default, all monitoring items are displayed. You can press the up or down key to select a monitoring item. Press the space bar to set the monitoring item, and press q to exit. +After %ST, %GUE, and %HYP are hidden, the following information is displayed: +```sh +vmtop - 2020-09-14 10:23:25 - 1.0 +Domains: 1 running + + DID VM/task-name PID %CPU EXThvc EXTwfe EXTwfi EXTmmioU EXTmmioK EXTfp EXTirq EXTsys64 EXTmabt EXTsum S P + 2 example 4054916 12.0 0 0 1213 14 1 144 68 168 0 1464 S 125 + |_ qemu-kvm 4054916 0.0 0 0 0 0 0 0 0 0 0 0 S 125 + |_ qemu-kvm 4054928 0.0 0 0 0 0 0 0 0 0 0 0 S 119 + |_ signalfd_com 4054929 0.0 0 0 0 0 0 0 0 0 0 0 S 120 + |_ IO mon_iothr 4054932 0.0 0 0 0 0 0 0 0 0 0 0 S 117 + |_ CPU 0/KVM 4054933 2.0 0 0 303 6 0 29 10 35 0 354 S 98 + |_ CPU 1/KVM 4054934 4.0 0 0 279 0 0 39 17 49 0 345 S 1 + |_ CPU 2/KVM 4054935 3.0 0 0 283 0 0 33 20 40 0 343 S 122 + |_ CPU 3/KVM 4054936 3.0 0 0 348 8 1 43 21 44 0 422 S 110 + |_ memory_lock 4054940 0.0 0 0 0 0 0 0 0 0 0 0 S 126 + |_ vnc_worker 4054944 0.0 0 0 0 0 0 0 0 0 0 0 S 118 + |_ worker 1794 0.0 0 0 0 0 0 0 0 0 0 0 S 126 +``` +%ST, %GUE, and %HYP will not be displayed on the screen. diff --git a/docs/en/docs/20.09/docs/Virtualization/vm-configuration.md b/docs/en/docs/20.09/docs/Virtualization/vm-configuration.md index 5c177e8cb319a052acd803b73eb20a023db87b58..e42e9ad02c921e04dec6a15df3af9f24b8736777 100644 --- a/docs/en/docs/20.09/docs/Virtualization/vm-configuration.md +++ b/docs/en/docs/20.09/docs/Virtualization/vm-configuration.md @@ -277,7 +277,7 @@ In this example, two I/O threads, one block disk device and one CD, are configur - + @@ -777,7 +777,7 @@ An XML configuration file of AArch64 VM, which contains basic elements. The foll - + diff --git a/docs/en/docs/20.09/docs/userguide/images/Maintainer.jpg b/docs/en/docs/20.09/docs/userguide/images/Maintainer.jpg new file mode 100644 index 0000000000000000000000000000000000000000..45912da4e7915715df0f598b9429f63bc8695667 Binary files /dev/null and b/docs/en/docs/20.09/docs/userguide/images/Maintainer.jpg differ diff --git a/docs/en/docs/20.09/docs/userguide/images/PatchTracking.jpg b/docs/en/docs/20.09/docs/userguide/images/PatchTracking.jpg new file mode 100644 index 0000000000000000000000000000000000000000..3bac7d2f1b4a228da8d273cdaef55f2d33792fab Binary files /dev/null and b/docs/en/docs/20.09/docs/userguide/images/PatchTracking.jpg differ diff --git a/docs/en/docs/20.09/docs/userguide/images/pkgship_outline.png b/docs/en/docs/20.09/docs/userguide/images/pkgship_outline.png new file mode 100644 index 0000000000000000000000000000000000000000..6fe1247c22c6b12a83aa01a5812c444f1667b952 Binary files /dev/null and b/docs/en/docs/20.09/docs/userguide/images/pkgship_outline.png differ diff --git a/docs/en/docs/20.09/docs/userguide/overview.md b/docs/en/docs/20.09/docs/userguide/overview.md new file mode 100644 index 0000000000000000000000000000000000000000..eceff8ff053b133f37bf2cfc85cfaa89e0519a2c --- /dev/null +++ b/docs/en/docs/20.09/docs/userguide/overview.md @@ -0,0 +1 @@ +This document describes the toolkit used for the openEuler release, including the overview, installation, and usage of tools. diff --git a/docs/en/docs/20.09/docs/userguide/patch-tracking.md b/docs/en/docs/20.09/docs/userguide/patch-tracking.md new file mode 100644 index 0000000000000000000000000000000000000000..a83d4ac20f0bb89cceee22af031be6b25c22b238 --- /dev/null +++ b/docs/en/docs/20.09/docs/userguide/patch-tracking.md @@ -0,0 +1,338 @@ +# patch-tracking + + + +- [patch-tracking](#patch-tracking) + - [Overview](#overview) + - [Architecture](#architecture) + - [C/S Architecture](#cs-architecture) + - [Core Procedure](#core-procedure) + - [Data structure](#data-structure) + - [Tool Deployment](#tool-deployment) + - [Downloading Software](#downloading-software) + - [Installing the Tool](#installing-the-tool) + - [Generating a Certificate](#generating-a-certificate) + - [Configuring Parameters](#configuring-parameters) + - [Starting the Patch Tracking Service](#starting-the-patch-tracking-service) + - [Tool Usage](#tool-usage) + - [FAQ](#faq) + - [When I access api.github.com, the connection is refused.](#when-i-access-apigithubcom-the-connection-is-refused) + + + + +## Overview + +During the development of the openEuler release, the latest code of each software package in the upstream community needs to be updated in a timely manner to fix function bugs and security issues, preventing the openEuler release from defects and vulnerabilities. + +This tool manages the patches for software packages, proactively monitors the patches submitted by the upstream community, automatically generates patches, submits issues to the corresponding Maintainer, and verifies basic patch functions to reduce the verification workload and help the Maintainer make decisions quickly. + +## Architecture + +### C/S Architecture + +The patch-tracking uses the C/S architecture. + +The patch-tracking is located in the server. It executes patch tracking tasks, including maintaining tracking items, identifying branch code changes in the upstream repository and generating patch files, and submitting issues and PRs to Gitee. In addition, the patch-tracking provides RESTful APIs for adding, deleting, modifying, and querying tracking items. + +The patch-tracking-cli is a command line tool located in the client. It invokes the RESTful APIs of the patch-tracking to add, delete, modify, and query tracking items. + +### Core Procedure + +1， Patch tracking service procedure + +The procedure for handling the submitted patch is as follows: + +1. Add the tracking item using the command line tool. +2. Automatically obtain patch files from the upstream repository (for example, GitHub) that is configured for the tracking item. +3. Create a temporary branch and submit the obtained patch file to the temporary branch. +4. Automatically submit an issue to the corresponding repository and generate the PR associated with the issue. + +![PatchTracking](./images/PatchTracking.jpg) + +2， Procedure for the Maintainer to handle the submitted patch + +The procedure for handling the submitted patch is as follows: + +1. The Maintainer analyzes the PR. +2. Execute the continuous integration (CI). After the CI is successfully executed, determine whether to merge the PR. + +![Maintainer](./images/Maintainer.jpg) + +### Data structure + +* Tracking table + +| No. | Name | Description | Type | Key | Is Null Allowed | +| :--: | --------------- | ------------------------------------------------------------ | ------- | ------- | --------------- | +| 1 | id | Sequence number of the tracking item of the self-added patch | int | - | No | +| 2 | version_control | Version control system type of the upstream SCM | String | - | No | +| 3 | scm_repo | Upstream SCM repository address | String | - | No | +| 4 | scm_branch | Upstream SCM tracking branch | String | - | No | +| 5 | scm_commit | Latest Commit ID processed by the upstream code | String | - | Yes | +| 6 | repo | Address of the Gitee repository where the package source code is stored | String | Primary | No | +| 7 | branch | Branch of the Gitee repository where the package source code is stored | String | Primary | No | +| 8 | enabled | Indicating whether to start tracking | Boolean | - | No | + +* Issue table + +| No. | Name | Description | Type | Key | Is Null Allowed | +| :--: | ------ | ------------------------------------------------------------ | ------ | ------- | --------------- | +| 1 | issue | Issue No. | String | Primary | No | +| 2 | repo | Address of the Gitee repository where the package source code is stored | String | - | No | +| 3 | branch | Branch of the Gitee repository where the package source code is stored | String | - | No | + +## Tool Deployment + +### Downloading Software + +The repo source is officially released at https://repo.openeuler.org/. + +The RPM package can be obtained from https://build.openeuler.org/package/show/openEuler:20.09/patch-tracking. + +### Installing the Tool + +Method 1: Install the patch-tracking from the repo source. + +1. Use DNF to mount the repo source (The repo source of 20.09 or later is required. For details, see the [Application Development Guide](https://openeuler.org/zh/docs/20.03_LTS/docs/ApplicationDev/%E5%BC%80%E5%8F%91%E7%8E%AF%E5%A2%83%E5%87%86%E5%A4%87.html)). Run the following command to download and install the patch-tracking and its dependencies. + +2. Run the following command to install the `patch-tracking`: + + ```shell script + dnf install patch-tracking + ``` + +Method 2: Install the patch-tracking using the RPM package. + +1. Install the required dependencies. + + ```shell script + dnf install python3-uWSGI python3-flask python3-Flask-SQLAlchemy python3-Flask-APScheduler python3-Flask-HTTPAuth python3-requests python3-pandas + ``` + +2. `patch-tracking-1.0.0-1.oe1.noarch.rpm` is used as an example. Run the following command to install the patch-tracking. + + ```shell script + rpm -ivh patch-tracking-1.0.0-1.oe1.noarch.rpm + ``` + +### Generating a Certificate + +Run the following command to generate a certificate: + +```shell script +openssl req -x509 -days 3650 -subj "/CN=self-signed" \ +-nodes -newkey rsa:4096 -keyout self-signed.key -out self-signed.crt +``` + +Copy the generated `self-signed.key` and `self-signed.crt` files to the **/etc/patch-tracking** directory. + +### Configuring Parameters + +Configure the corresponding parameters in the configuration file. The path of the configuration file is `/etc/patch-tracking/settings.conf`. + +1. Configure the service listening address. + + ``` + LISTEN = "127.0.0.1:5001" + ``` + +2. GitHub Token is used to access the repository information hosted in the upstream open source software repository of GitHub. For details about how to create a GitHub token, see [Creating a personal access token](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token). + + ``` + GITHUB_ACCESS_TOKEN = "" + ``` + +3. For a repository that is hosted on Gitee and needs to be tracked, configure a Gitee Token with the repository permission to submit patch files, issues, and PRs. + + ``` + GITEE_ACCESS_TOKEN = "" + ``` + +4. Scan the database as scheduled to detect whether new or modified tracking items exist and obtain upstream patches for the detected tracking items. Set the interval of scanning and the unit is second. + + ``` + SCAN_DB_INTERVAL = 3600 + ``` + +5. When the command line tool is running, you need to enter the user name and password hash value for the authentication for the POST interface. + + ``` + USER = "admin" + + PASSWORD = "" + ``` + +> The default value of `USER` is `admin`. + +Run the following command to obtain the password hash value. **Test@123** is the configured password. + +``` +[root]# generate_password Test@123 +pbkdf2:sha256:150000$w38eLeRm$ebb5069ba3b4dda39a698bd1d9d7f5f848af3bd93b11e0cde2b28e9e34bfbbae +``` + +> The password hash value must meet the following complexity requirements: +> +> * The length is more than or equal to 6 bytes. +> * The password must contain uppercase letters, lowercase letters, digits, and special characters (~!@#%\^\*-\_=+). + +Add the password hash value `pbkdf2:sha256:150000$w38eLeRm$ebb5069ba3b4dda39a698bd1d9d7f5f848af3bd93b11e0cde2b28e9e34bfbbae` to the quotation marks of `PASSWORD = ""`. + +### Starting the Patch Tracking Service + +You can use either of the following methods to start the service: + +* Use the systemd mode. + + ``` + systemctl start patch-tracking + ``` + +* Run the executable program. + + ``` + /usr/bin/patch-tracking + ``` + +## Tool Usage + +1， Adding a Tracking Item + +You can associate the software repository and branch to be tracked with the corresponding upstream open source software repository and branch in any of the following ways: + +* Using CLI + +Parameter description: + +> --user: User name to be authenticated for the POST interface. It is the same as the USER parameter in the **settings.conf** file. +> --password: Password to be authenticated for the POST interface. It is the password string corresponding to the PASSWORD hash value in the **settings.conf** file. +> --server: URL for starting the patch tracking service, for example, 127.0.0.1:5001. +> --version\_control: Control tool of the upstream repository version. Only GitHub is supported. +> --repo: Name of the repository to be tracked, in the format of organization/repository. +> +> --branch: Branch name of the repository to be tracked. +> --scm\_repo: Name of the upstream repository to be tracked, in the GitHub format of organization/repository. +> --scm\_branch: Branch of the upstream repository to be tracked. +> +> --enabled: Indicates whether to automatically track the repository. + +For example: + +```shell script +patch-tracking-cli add --server 127.0.0.1:5001 --user admin --password Test@123 --version_control github --repo testPatchTrack/testPatch1 --branch master --scm_repo BJMX/testPatch01 --scm_branch test --enabled true +``` + +* Using a Specified File + +Parameter description: + +> --server: URL for starting the patch tracking service, for example, 127.0.0.1:5001. +--user: User name to be authenticated for the POST interface. It is the same as the USER parameter in the **settings.conf** file. +--password: Password to be authenticated for the POST interface. It is the password string corresponding to the PASSWORD hash value in the **settings.conf** file. +--file: YAML file path. + +Add the information about the repository, branch, version management tool, and whether to enable monitoring to the YAML file (for example, **tracking.yaml**). The file path is used as the command of the `--file` to invoke the input parameters. + +For example: + +```shell script +patch-tracking-cli add --server 127.0.0.1:5001 --user admin --password Test@123 --file tracking.yaml +``` + +The format of the YAML file is as follows. The content on the left of the colon (:) cannot be modified, and the content on the right of the colon (:) needs to be set based on the site requirements. + +```shell script +version_control: github +scm_repo: xxx/xxx +scm_branch: master +repo: xxx/xxx +branch: master +enabled: true +``` + +> version\_control: Control tool of the upstream repository version. Only GitHub is supported. +scm\_repo: Name of the upstream repository to be tracked, in the GitHub format of organization/repository. +scm\_branch: Branch of the upstream repository to be tracked. +repo: Name of the repository to be tracked, in the format of organization/repository. +branch: Branch name of the repository to be tracked. +enabled: Indicates whether to automatically track the repository. + +* Using a Specified Directory + +Place multiple `xxx.yaml` files in a specified directory, such as the `test_yaml`, and run the following command to record the tracking items of all YAML files in the specified directory. + +Parameter description: + +> --user: User name to be authenticated for the POST interface. It is the same as the USER parameter in the **settings.conf** file. +--password: Password to be authenticated for the POST interface. It is the password string corresponding to the PASSWORD hash value in the **settings.conf** file. +--server: URL for starting the patch tracking service, for example, 127.0.0.1:5001. +--dir: Path where the YAML file is stored. + +```shell script +patch-tracking-cli add --server 127.0.0.1:5001 --user admin --password Test@123 --dir /home/Work/test_yaml/ +``` + +2， Querying a Tracking Item + +Parameter description: + +> --server: (Mandatory) URL for starting the patch tracking service, for example, 127.0.0.1:5001. +--table: (Mandatory) Table to be queried. +--Repo: (Optional) repo to be queried. Query all content in the table if this parameter is not configured. +--branch: (Optional) Branch to be queried. + +```shell script +patch-tracking-cli query --server --table tracking +``` + +The website can be accessed properly. + +```shell script +patch-tracking-cli query --server 127.0.0.1:5001 --table tracking +``` + +3， Querying the Generated Issue + +```shell script +patch-tracking-cli query --server --table issue +``` + +For example: + +```shell script +patch-tracking-cli query --server 127.0.0.1:5001 --table issue +``` + +4， Deleting a Tracking Item + +```shell script +patch-tracking-cli delete --server SERVER --user USER --password PWD --repo REPO [--branch BRANCH] +``` + +For example: + +```shell script +patch-tracking-cli delete --server 127.0.0.1:5001 --user admin --password Test@123 --repo testPatchTrack/testPatch1 --branch master +``` + +> You can delete a single piece of data from a specified repo or branch. You can also delete data of all branches in a specified repo. + +5， Checking Issues and PRs on Gitee + +Log in to Gitee and check the software project to be tracked. On the Issues and Pull Requests tab pages of the project, you can see the item named in `[patch tracking] TIME`, for example, the `[patch tracking] 20200713101548`. This item is the issue and PR of the patch file that is just generated. + +## FAQ + +### When I access api.github.com, the connection is refused. + +#### Symptom + +During the operation of the patch-tracking, the following error message may occur: +``` + 9月 21 22:00:10 localhost.localdomain patch-tracking[36358]: 2020-09-21 22:00:10,812 - patch_tracking.util.github_api - WARNING - HTTPSConnectionPool(host='api.github.com', port=443): Max retries exceeded with url: /user (Caused by NewConnectionError(': Failed to establish a new connection: [Errno 111] Connection refused')) +``` + +#### Cause Analysis + +The preceding problem is caused by the unstable network access between the patch-tracking and GitHub API. Ensure that the patch-tracking is operating in a stable network environment (for example, HUAWEI CLOUD Hong Kong). \ No newline at end of file diff --git a/docs/en/docs/20.09/docs/userguide/pkgship.md b/docs/en/docs/20.09/docs/userguide/pkgship.md new file mode 100644 index 0000000000000000000000000000000000000000..3e3a4fdc6ab4410d543ec6ed837875a956cffd8e --- /dev/null +++ b/docs/en/docs/20.09/docs/userguide/pkgship.md @@ -0,0 +1,399 @@ +# pkgship + + + +- [pkgship](#pkgship) + - [Overview](#overview) + - [Architecture](#architecture) + - [Downloading Software](#downloading-software) + - [Operating Environments](#operating-environments) + - [Installing the Tool](#installing-the-tool) + - [Configuring Parameters](#configuring-parameters) + - [Starting and Stopping Services](#starting-and-stopping-services) + - [Tool Usage](#tool-usage) + + + +## Overview + +pkgship is a query tool used to manage the dependency of OS software packages and provide a complete dependency graph. The pkgship provides functions such as software package dependency query, lifecycle management, and patch query. + +1. Software package dependency query: Allows community personnel to understand the impact on software when software packages are introduced, updated, or deleted. +2. Lifecycle management: Tracks the release status of upstream software packages so that the maintenance personnel can learn about the current software status and upgrade the software properly in a timely manner. +3. Patch query: Allows community personnel to learn about the patches in the openEuler software package and obtain the patch information. For details, see [patch-tracking](patch-tracking.md). + +## Architecture + +The system is developed using Flask-RESTful and adopts the SQLAlchemy ORM query framework. + +![avatar](./images/pkgship_outline.png) + +## Downloading Software + +* The repo source is officially released at +* You can obtain the source code at +* You can obtain the RPM package of the beta version at + +## Operating Environments + +* The available memory is greater than 700 MB. +* The Python version is 3.8 or later. +* The SQLite version is 3.32 or later. + +## Installing the Tool + +You can use either of the following methods to install the tool: + +* Method 1: Mount the repo source using DNF. +Use DNF to mount the repo source where the pkgship is located (for details, see the [Application Development Guide](https://openeuler.org/zh/docs/20.09/docs/ApplicationDev/%E5%BC%80%E5%8F%91%E7%8E%AF%E5%A2%83%E5%87%86%E5%A4%87.html)), run the following command to download and install the pkgship and its dependencies: + + ```bash + dnf install pkgship + ``` + +* Method 2: Install the RPM package. Download the RPM package of the pkgship and run the following command to install the pkgship (x.x-x indicates the version number and needs to be replaced with the actual one): + + ```bash + rpm -ivh pkgship-x.x-x.oe1.noarch.rpm + ``` + + or the following command: + + ```bash + dnf install pkgship-x.x-x.oe1.noarch.rpm + ``` + +## Configuring Parameters + +1. Configure the parameters in the configuration file. The default configuration file of the system is stored in **/etc/pkgship/packge.ini**. Modify the configuration file as required. + + ```basn + vim /etc/pkgship/package.ini + ``` + + ```ini + [SYSTEM CONFIGURATION] + + ; Directory for storing the YAML file imported during database initialization. The YAML file records the location of the imported SQLite file. + init_conf_path=/etc/pkgship/conf.yaml + + ; Path for storing the SQLite file that is successfully imported + data_base_path=/var/run/pkgship_dbs + + ; Write port + write_port=8080 + + ; Query port + query_port=8090 + + ; Write permission access IP address + write_ip_addr=127.0.0.1 + + ; Query permission access IP address + query_ip_addr=127.0.0.1 + + ; Address of the remote service. The command line can directly invoke the remote service to complete data requests. You only need to add the -remote parameter to the end of each command line. + remote_host=https://api.openeuler.org/pkgmanage + + [LOG] + + ; Path for storing logs + log_path=/var/log/pkgship/ + + ; Log level as follows: + ; INFO DEBUG WARNING ERROR CRITICAL + log_level=INFO + + ; Log name + log_name=log_info.log + + ; Number of logs that are dynamically created after the size of a log file reaches the upper limit. + backup_count=10 + + ; Size of each log file + max_bytes=314572800 + + [uWSGI SERVICE CONFIGURATION] + + ; Path for storing uwsgi log + daemonize=/var/log/uwsgi.log + + ; Size of data transmitted at the front- and back-end + buffer-size=65536 + + ; HTTP connection time + http-timeout=600 + + ; Server response time + harakiri=600 + + [TIMEDTASK] + + ; Whether to enable scheduled tasks + open=True + + ; Set the time when a scheduled task is triggered + hour=3 + minute=0 + + [LIFECYCLE] + ; Remote storage address of the YAML address of each package + warehouse_remote=https://gitee.com/openeuler/openEuler-Advisor/raw/master/upstream-info/ + + ; When executing a scheduled task, you can enable multi-thread execution and set the number of threads in the thread pool based on the server configuration. + pool_workers=10 + + ; Warehouse name + warehouse=src-openeuler + + ``` + +2. Create a YAML configuration file to initialize the database. By default, the conf.yaml file is stored in the **/etc/pkgship/** directory. Based on this configuration, the pkgship reads the name of the database to be created and the SQLite file to be imported. An example of the conf.yaml file is as follows: + + ```yaml + - dbname: openEuler-20.09 + src_db_file: /etc/pkgship/src.sqlite + bin_db_file: /etc/pkgship/bin.sqlite + lifecycle: enable + priority: 1 + ``` + +> To change the storage path, change the value of **init\_conf\_path** in the **package.ini** file. + +## Starting and Stopping Services + +The pkgship uses the uWSGI web server. The commands for starting and stopping the service are as follows. You can specify whether to start the read-only (write-only) service or start the read and write services at the same time. + +```bash +pkgshipd start [manage/selfpkg] + +pkgshipd stop [manage/selfpkg] +``` + +## Tool Usage + +1. Initialize the database. + + > Application scenario: After the service is started, to query the package information and package dependency in the corresponding database, such as Mainline and openEuler 20.09, you need to import the SQLite (including the source code library and binary library), which is generated by the database using createrepo, to the service, and generate the corresponding DB file. When the **lifecycle** parameter of the database is set to enable in the conf.yaml file, a corresponding table is generated in **lifecycle.db** to record database information. The database table name (**tablename**) is read from this file subsequently. The **\[-filepath]** parameter is optional. + + ```bash + pkgship init [-filepath path] + ``` + + > Parameter description: +**-filepath**: Specifies the path of the initialized configuration file. You can use either a relative path or an absolute path. If no parameter is specified, the default configuration is used for initialization. + +2. Query a single package. + + You can query the information about a source code package (**packagename**) in a specified database table (**tablename**). + + > Application scenario: You can query information about a specific source code package in a specified database. The **packagename** and **tablename** are mandatory. + + ```bash + pkgship single packagename tablename + ``` + + > Parameter description: +**packagename**: Specifies the name of the source code package to be queried. +**tablename**: Specifies the database name. + +3. Query all packages. + + Query information about all packages in the database. + + > Application scenario: You can query information about all software packages in a specified database. The **tablename** is mandatory, and the **\[-packagename]** and **\[-maintainer]** are optional. + + ```bash + pkgship list tablename [-packagename pkgName] [-maintainer maintainer] + ``` + + > Parameter description: +**tablename**: Specifies the database name. +**-packagename**: Matches the package whose name contains the parameter string. +**-maintainer**: Matches the package in which **maintainer** is a parameter. + +4. Query the installation dependency. + + Query the installation dependency of the binary package (binaryName). + + > Application scenario: When you need to install the binary package A, you need to install B, the installation dependency of A, and C, the installation dependency of B, etc. A can be successfully installed only after all the installation dependencies are installed in the system. Therefore, before installing the binary package A, you may need to query all installation dependencies of A. You can run the following command to query multiple databases based on the default priority of the platform, and to customize the database query priority. + + ```bash + pkgship installdep binaryName [-dbs dbName1 dbName2...] + ``` + + > Parameter description: +**-dbs**: Specifies the database query priority. **dbName** indicates the database name. + +5. Query the compilation dependency. + + Query all compilation dependencies of the source code package (**sourceName**). + + > Application scenario: To compile the source code package A, you need to install B, the compilation dependency package of A. To install B, you need to obtain all installation dependency packages of B. Therefore, before compiling the source code package A, you may need to query the compilation dependencies of A and all installation dependencies of these compilation dependencies. You can run the following command to query multiple databases based on the default priority of the platform, and to customize the database query priority. + + ```bash + pkgship builddep sourceName [-dbs dbName1 dbName2...] + ``` + + > Parameter description: +**-dbs**: Specifies the database query priority. **dbName** indicates the database name. + +6. Query the self-compilation and self-installation dependencies. + + Query the installation and compilation dependencies of a specified binary package (**binaryName**) or source code package (**sourceName**). In the command, **\[pkgName]** indicates the name of the binary package or source code package to be queried. When querying a binary package, you can query all installation dependencies of the binary package, and the compilation dependencies of the source code package corresponding to the binary package, as well as all installation dependencies of these compilation dependencies. When querying a source code package, you can query its compilation dependency, and all installation dependencies of these compilation dependencies, as well as all installation dependencies of the binary packages generated by the source code package. In addition, you can run this command together with the corresponding parameters to query the self-compilation dependency of a software package and the dependency of a subpackage. + + > Application scenario: If you want to introduce a new software package based on the existing version library, you need to introduce all compilation and installation dependencies of the software package. You can run this command to query these two dependency types at the same time to know the packages introduced by the new software package, and to query binary packages and source code packages. + + ```bash + pkgship selfbuild [pkgName] [-dbs dbName1 dbName2 ] [-t source] [-s 1] [-w 1] + ``` + + > Parameter description: +**-dbs:** Specifies the database priority. **dbName** indicates the database name. The following is an example: + + > ```bash + > pkgship selfbuild pkgName -dbs dbName1 dbName2 + > ``` + + > **-t source/binary**: Specifies whether the package **pkgName** to be queried is a source code package or a binary package. If **-t** is not added, the package is a binary package by default. +**-s**: This parameter is added to query all installation dependencies and compilation dependencies of the software package (that is, compilation dependencies of the source code package on which compilation depends), and all installation dependencies of the compilation dependencies. In the command, **0** following the **-s** indicates that the self-compilation dependency is not queried, and 1 indicates that the self-compilation dependency is queried. The default value is **0**, and you can specify the value to **1**. If the **-s** is not added, all installation dependencies, layer-1 compilation dependencies, and layer-1 compilation dependencies of the software package are queried. The following is an example of querying self-compilation dependencies: + + > ```bash + > pkgship selfbuild pkgName -t source -s 1 + > ``` + + > **-w**: When a binary package is introduced and this parameter is added, the source code package corresponding to the binary package and all binary packages generated by the source code package are displayed in the query result. In the command, **0** following **-w** indicates that the corresponding subpackage is not queried, and **1** indicates that the corresponding subpackage is queried. The default value is **0**, and you can specify the value to **1**. When **-w** is not added, only the corresponding source code package is displayed in the query result when a binary package is introduced. The following is an example of querying a subpackage: + + > ```bash + > pkgship selfbuild pkgName -w 1 + > ``` + +7. Query dependency. +Query the packages that depend on the source code package (**sourceName**) in a database (**dbName**). + + > Application scenario: You can run this command to query the software packages that will be affected by the upgrade or deletion of the software source code package A. This command displays the source code packages (for example, B) whose compilation depends on all binary packages generated by the source code package A, and the binary packages (for example, C1) whose installation depends on all binary packages generated by A. This command also displays the source code packages (for example, D) whose compilation depends on C1 and the binary package generated by B, and the binary packages (for example, E1) whose installation depends on C1 and the binary package generated by B, etc. Iterate the packages that depend on these binary packages. **\[-w 0/1]** is an optional parameter. The following is an example: + + ```bash + pkgship bedepend sourceName dbName [-w 1] + ``` + + > Parameter description +**-w (0/1)**: If the command does not contain configuration parameters or **\[-w 0]**, by default, the query result does not contain the subpackage of the corresponding binary package. When the command is followed by the configuration parameter or **\[-w 1]**, the dependency of the binary package C1 is queried, as well as the dependency of other binary packages (for example, C2 and C3) generated by C, the source code package corresponding to C1. + +8. Modify package information. + + > Application scenario: You can modify the information about the maintainer and maintenance level of a specified source code package. **[-Packagename]**, **\[-maintainer]**, **\[-maintainlevel]**, **\[-filefolder]**, and **\[--batch]** are optional parameters. + + You can modify the information with either of the following methods: +Method 1: Specify the source code package name (**packagename**) to modify the information about the maintainer (**Newmaintainer**) and maintenance level (**Newmaintainlevel**) of the source code package. The following is an example: + + ```bash + pkgship updatepkg [-packagename packagename] [-maintainer Newmaintainer] [-maintainlevel Newmaintainlevel] + ``` + + > Parameter description: +**-packagename**: Specifies the name of the package to be maintained. +**-maintainer**: Specifies the maintainer of the update package. +**-maintainlevel**: Specifies the maintenance level of the update package. The value ranges from 1 to 4, and the default value is **1**. + + Method 2: Specify the file path, and the maintainer, and maintenance level of the batch update package. The **--batch** parameter must be added to this command. The following is an example: + + ```bash + pkgship updatepkg [--batch] [-filefolder path] + ``` + + > Parameter description: +**-filefolder**: Specifies the YAML file where the package information is stored. The specified directory can contain only the updated YAML files. +**--batch**: Specifies the update in batches. This parameter must be used together with the **\[-filefolder]** parameter. + + You can create a file named A.yaml, set the package name to A, and specify the YAML content to modify the package information. +The YAML format of the package information is as follows: + + ``` + maintainer：Newmaintainlevel + maintainlevel： Newmaintainlevel + ``` + +9. Delete databases. + + > Application scenario: Delete a specified database (**dbName**). + + ```bash + pkgship rm dbName + ``` + +10. Query table information. + + > Application scenario: View all data tables in the current lifecycle database. + + ```bash + pkgship tables + ``` + +11. Query issues. + + > Application scenario: View information about all issues in all source code packages. The optional parameters include **\[-packagename]**, **\[-issue\_type]**, **\[-issue\_status]**, **\[-maintainer]**, **\[-page N]**, and **\[-pagesize pageSize]**. + + ```bash + pkgship issue [-packagename pkgName],[-issue_type issueType],[-issue_status issueStatus],[-maintainer maintainer],[-page N],[-pagesize pageSize] + ``` + + > Parameter description: +**-packagename**: Specifies the package name for fuzzy query. +**-issue\_type**: Specifies the issue type for query. +**-issue\_status**: Specifies the issue status for query. +**-maintainer**: Specifies a maintainer for query. +**-page**: Specifies the data on page N to be queried. +**-pagesize**: Specifies the number of data records displayed on each page. + + ```bash + Run the following command to specify a package name for fuzzy search: + pkgship issue -packagename pkgName + ``` + + ```bash + Run the following command to specify an issue type for query: + pkgship issue -issue_type issueType + ``` + + ```bash + Run the following command to specify an issue status for query: + pkgship issue -issue_status issueStatus + ``` + + ```bash + Run the following command to specify a maintainer for query: + pkgship issue -maintainer maintainer + ``` + + ```bash + Run the following command to specify the data of page N for query: + pkgship issue -page N + ``` + + ```bash + Run the following command to specify the number of data items of each page for query: + pkgship issue -pagesize pageSize + ``` + +12. Update the lifecycle of the software package. + + > Application scenario: Update the information about the issue, maintainer, and maintenance level of all software packages in the lifecycle table. The optional parameters include **\[--issue]** and **\[--package]**. + + ```bash + pkgship update [--issue] [--package] + ``` + + > Parameter description: +**--issue**: Updates the issue information of all software packages in the lifecycle table. Based on the software package names in the lifecycle table, the system crawls the issue information corresponding to the software package. +**--package**: Updates the information about the lifecycle, maintainer, and maintenance level of all software packages in the lifecycle table. + + ```bash + Run the following command to update the issue information of all software packages in the lifecycle table: + pkgship update --issue + ``` + + ```bash + Run the following command to update the lifecycles, maintainers, and maintenance levels of all software packages in the lifecycle table: + pkgship update --package + ``` \ No newline at end of file diff --git a/docs/en/docs/20.09/menu/menu.json b/docs/en/docs/20.09/menu/menu.json index 43315eb278ad84d70bb740fe90d561804c45e35c..c74342c0c61185afa88d3efd1a73bd0cb13b34e6 100644 --- a/docs/en/docs/20.09/menu/menu.json +++ b/docs/en/docs/20.09/menu/menu.json @@ -331,6 +331,11 @@ "path": "docs/Virtualization/best-practices", "children": [] }, + { + "label": "Tool Guide", + "path": "docs/Virtualization/tool-guide", + "children": [] + }, { "label": "Appendix", "path": "docs/Virtualization/appendix", @@ -338,6 +343,47 @@ } ] }, + { + "label": "StratoVirt User Guide", + "path": "docs/StratoVirt/StratoVrit_guidence", + "children": [ + { + "label": "Introduction to StratoVirt", + "path": "docs/StratoVirt/StratoVirt_Intoduction", + "children": [] + }, + { + "label": "Installing StratoVirt", + "path": "docs/StratoVirt/Install_StratoVirt", + "children": [] + }, + { + "label": "Preparing the Environment", + "path": "docs/StratoVirt/Prepare_env", + "children": [] + }, + { + "label": "Configuring a VM", + "path": "docs/StratoVirt/VM_configuration", + "children": [] + }, + { + "label": "Managing the VM Lifecycle", + "path": "docs/StratoVirt/Manage_life_cycle", + "children": [] + }, + { + "label": "Managing VM resources", + "path": "docs/StratoVirt/Manage_resource", + "children": [] + }, + { + "label": "Interconnecting with the iSula Secure Container", + "path": "docs/StratoVirt/Interconnect_isula", + "children": [] + } + ] + }, { "label": "Container User Guide", "path": "docs/Container/container", @@ -686,4 +732,4 @@ } ] } - ] \ No newline at end of file + ] diff --git a/docs/zh/docs/20.09/docs/ApplicationDev/FAQ.md b/docs/zh/docs/20.09/docs/ApplicationDev/FAQ.md index 7dbfa6fcb6eaf58e7e09093cdee6ad85d292e154..8125fbab883efb8e46b2723ad8be0b34932858e7 100644 --- a/docs/zh/docs/20.09/docs/ApplicationDev/FAQ.md +++ b/docs/zh/docs/20.09/docs/ApplicationDev/FAQ.md @@ -6,7 +6,7 @@ -## 使用systemctl和top命令查询libvirtd服务占用内存不同 +## 部分依赖java-devel的应用程序自编译失败 ### 问题描述 diff --git "a/docs/zh/docs/20.09/docs/Container/isula-build\346\236\204\345\273\272\345\267\245\345\205\267.md" "b/docs/zh/docs/20.09/docs/Container/isula-build\346\236\204\345\273\272\345\267\245\345\205\267.md" index af20374fcd64ce84478f48b7d86cf768321dfb84..7e21c46fa026cfab1bb7fcc3f79e4b297a96c739 100644 --- "a/docs/zh/docs/20.09/docs/Container/isula-build\346\236\204\345\273\272\345\267\245\345\205\267.md" +++ "b/docs/zh/docs/20.09/docs/Container/isula-build\346\236\204\345\273\272\345\267\245\345\205\267.md" @@ -1,3 +1,5 @@ +# 容器镜像构建 + * [安装](#安装) @@ -33,6 +35,8 @@ +## 概述 + isula-build是iSula容器团队推出的容器镜像构建工具，支持通过Dockerfile文件快速构建容器镜像。 isula-build采用服务端/客户端模式，其中，isula-build为客户端，提供了一组命令行工具，用于镜像构建及管理等；isula-builder为服务端，用于处理客户端管理请求，作为守护进程常驻后台。 @@ -43,9 +47,9 @@ isula-build采用服务端/客户端模式，其中，isula-build为客户端， - isula-build当前仅支持Docker镜像。 -# 安装 +## 安装 -## 环境准备 +### 环境准备 为了确保isula-build成功安装，需满足以下软件硬件要求。 @@ -53,7 +57,7 @@ isula-build采用服务端/客户端模式，其中，isula-build为客户端， - 支持的操作系统：openEuler - 用户具有root权限。 -### 安装isula-build +#### 安装isula-build 使用isula-build构建容器镜像，需要先安装以下软件包。 @@ -86,9 +90,9 @@ isula-build采用服务端/客户端模式，其中，isula-build为客户端， > **说明：** > 安装完成后，需要手工启动isula-build服务。启动请参见"管理服务"。 -# 配置与管理服务 +## 配置与管理服务 -## 配置服务 +### 配置服务 在安装完 isula-build 软件包之后，systemd 管理服务会以 isula-build 软件包自带的 isula-build 服务端默认配置启动 isula-build 服务。如果 isula-build 服务端的默认配置文件不能满足用户的需求，可以参考如下介绍进行定制化配置。需要注意的是，修改完默认配置之后，需要重启 isula-build 服务端使新配置生效，具体操作可参考下一章节。 @@ -133,14 +137,14 @@ isula-build采用服务端/客户端模式，其中，isula-build为客户端， -## 管理服务 +### 管理服务 目前 openEuler 采用 systemd 管理软件服务，isula-build 软件包已经自带了 systemd 的服务文件，用户安装完 isula-build 软件包之后可以直接通过 systemd 工具对它进行服务启停等操作。用户同样可以手动启动 isula-build 服务端软件。需要注意的是，同一个节点上不可以同时启动多个 isula-build 服务端软件。 >![](./public_sys-resources/icon-note.gif) **说明：** >同一个节点上不可以同时启动多个 isula-build 服务端软件。 -### 通过 systemd 管理（推荐方式） +#### 通过 systemd 管理（推荐方式） 用户可以通过如下 systemd 的标准指令控制 isula-build 服务的启动、停止、重启等动作： @@ -168,7 +172,7 @@ isula-build 软件包安装的 systemd 服务文件保存在 `/usr/lib/systemd/s sudo systemctl daemon-reload ``` -### 直接运行 isula-build 服务端 +#### 直接运行 isula-build 服务端 您也可以通过执行 isula-build 服务端命令（ isula-builder）的方式启动服务。其中，服务端启动配置，可通过isula-builder命令支持的 flags 设置。isula-build 服务端目前支持的 flags 如下： @@ -188,9 +192,9 @@ sudo systemctl daemon-reload sudo isula-builder --dataroot "/var/lib/isula-build" --debug=false ``` -# 使用指南 +## 使用指南 -## 前提条件 +### 前提条件 isula-build 构建 Dockerfile 内的 RUN 指令时依赖可执行文件 runc ，需要 isula-build 的运行环境上预装好 runc。安装方式视用户使用场景而定，如果用户不需要使用完整的 docker-engine 工具链，则可以仅安装 docker-runc rpm包： @@ -209,7 +213,7 @@ sudo yum install -y docker-engine -## 总体说明 +### 总体说明 isula-build 客户端提供了一系列命令用于构建和管理容器镜像，当前 isula-build 包含的命令行指令如下： @@ -236,7 +240,7 @@ isula-build 客户端提供了一系列命令用于构建和管理容器镜像 -## ctr-img: 容器镜像管理 +### ctr-img: 容器镜像管理 isula-build 将所有容器镜像管理相关命令划分在子命令 `ctr-img` 下，命令原型为： @@ -244,7 +248,7 @@ isula-build 将所有容器镜像管理相关命令划分在子命令 `ctr-img` isula-build ctr-img [command] ``` -### build: 容器镜像构建 +#### build: 容器镜像构建 ctr-img 的子命令 build 用于构建容器镜像，命令原型为： @@ -410,7 +414,7 @@ $ sudo isula-build ctr-img build --cap-add CAP_SYS_ADMIN --cap-add CAP_SYS_PTRAC -### image: 查看本地持久化构建镜像 +#### image: 查看本地持久化构建镜像 可通过images命令查看当前本地持久化存储的镜像： @@ -428,7 +432,7 @@ localhost:5000/library/alpine latest a24bb4013296 -### import: 导入容器基础镜像 +#### import: 导入容器基础镜像 openEuler会随版本发布一个容器基础镜像，比如openEuler-docker.x86_64.tar.xz。可以通过`ctr-img import`指令将它导入到 isula-build。 @@ -441,13 +445,13 @@ isula-build ctr-img import [flags] 使用举例： ```sh -$ sudo isula-build ctr-img import ./openEuler-docker.x86_64.tar.xz openeuler:20.03 +$ sudo isula-build ctr-img import ./openEuler-docker.x86_64.tar.xz openeuler:20.09 Import success with image id: 7317851cd2ab33263eb293f68efee9d724780251e4e92c0fb76bf5d3c5585e37 $ sudo isula-build ctr-img images ---------------------------------------------- -------------------- ----------------- ------------------------ ------------ REPOSITORY TAG IMAGE ID CREATED SIZE ---------------------------------------------- -------------------- ----------------- ------------------------ ------------ -openeuler 20.03 7317851cd2ab 2020-08-01 06:25:34 500 MB +openeuler 20.09 7317851cd2ab 2020-08-01 06:25:34 500 MB ---------------------------------------------- -------------------- ----------------- ------------------------ ------------ ``` @@ -456,7 +460,7 @@ openeuler 20.03 7317851cd2 -### load: 导入层叠镜像 +#### load: 导入层叠镜像 层叠镜像指的是通过 docker save 或 isula-build ctr-img save 等指令，将一个构建完成的镜像保存至本地之后，镜像压缩包内是一层一层 layer.tar 的镜像包。可以通过 ctr-img load 指令将它导入至 isula-build。 @@ -501,7 +505,7 @@ Loaded image as c07ddb44daa97e9e8d2d68316b296cc9343ab5f3d2babc5e6e03b80cd580478e -### rm: 删除本地持久化镜像 +#### rm: 删除本地持久化镜像 可通过rm命令删除当前本地持久化存储的镜像。命令原型为： @@ -524,7 +528,7 @@ Deleted: sha256:eeba1bfe9fca569a894d525ed291bdaef389d28a88c288914c1a9db7261ad12c -### save: 导出层叠镜像 +#### save: 导出层叠镜像 可通过save命令导出层叠镜像到本地磁盘。命令原型如下： @@ -562,7 +566,7 @@ Save success with image: 21c3e96ac411 -### tag: 给本地持久化镜像打标签 +#### tag: 给本地持久化镜像打标签 可使用tag命令给本地持久化的容器镜像打tag。命令原型如下： @@ -591,7 +595,7 @@ alpine v1 a24bb4013296 -## info: 查看运行环境与系统信息 +### info: 查看运行环境与系统信息 可以通过“isula-build info”指令查看 isula-build 目前的运行环境与系统信息。命令原型如下： @@ -628,7 +632,7 @@ $ sudo isula-build info -H oepkgs.net ``` -## login: 登录远端镜像仓库 +### login: 登录远端镜像仓库 用户可以运行 login 命令来登录远程镜像仓库。命令原型如下： @@ -659,7 +663,7 @@ $ sudo isula-build info -H Login Succeeded ``` -## logout: 退出远端镜像仓库 +### logout: 退出远端镜像仓库 用户可以运行 logout 命令来登出远程镜像仓库。命令原型如下： @@ -681,7 +685,7 @@ $ sudo isula-build info -H Removed authentications ``` -## version: 版本查询 +### version: 版本查询 可通过version命令查看当前版本信息： @@ -703,11 +707,11 @@ $ sudo isula-build info -H ``` -# 直接集成容器引擎 +## 直接集成容器引擎 isula-build可以与iSulad和docker集成，将构建好的容器镜像导入到容器引擎的本地存储中。 -## 与iSulad集成 +### 与iSulad集成 支持将构建成功的镜像直接导出到iSulad。 @@ -730,7 +734,7 @@ busybox 2.0 2d414a5cad6d 2020-08-01 06:41: > - 要求isula-build和iSulad在同一节点。 > - 直接导出镜像到iSulad时，isula-build client端需要将构建成功的镜像暂存成 `/var/tmp/isula-build-tmp-%v.tar` 再导入至 iSulad，用户需要保证 /var/tmp/ 目录有足够磁盘空间；同时如果在导出过程中 isula-build client进程被KILL或Ctrl+C终止，需要依赖用户手动清理 `/var/tmp/isula-build-tmp-%v.tar` 文件。 -## 与Docker集成 +### 与Docker集成 支持将构建成功的镜像直接导出到Docker daemon。 @@ -752,10 +756,10 @@ busybox 2.0 2d414a5c > > - 要求isula-build和Docker在同一节点。 -# 附录 +## 附录 -## 命令行参数说明 +### 命令行参数说明 **表1** ctr-img build 命令参数列表 @@ -802,11 +806,11 @@ busybox 2.0 2d414a5c | -------- | --------- | ------------------------------------ | | logout | -a, --all | 布尔值，是否登出所有已登陆的镜像仓库 | -## 通信矩阵 +### 通信矩阵 isula-build两个组件进程之间通过unix socket套接字文件进行通信，无端口通信。 -## 文件与权限 +### 文件与权限 - isula-build 所有的操作均需要使用 root 权限。 diff --git "a/docs/zh/docs/20.09/docs/Container/\345\256\271\345\231\250\345\274\225\346\223\216-4.md" "b/docs/zh/docs/20.09/docs/Container/\345\256\271\345\231\250\345\274\225\346\223\216-4.md" index a230e281993e13fb393c217bbce61dde05a1d314..1741c561a9434ae2a973e997ddcd8d7d59eb26c9 100644 --- "a/docs/zh/docs/20.09/docs/Container/\345\256\271\345\231\250\345\274\225\346\223\216-4.md" +++ "b/docs/zh/docs/20.09/docs/Container/\345\256\271\345\231\250\345\274\225\346\223\216-4.md" @@ -125,11 +125,7 @@ docker命令支持多个参数选项，对于参数选项有以下约定：

设置运行时执行选项。

例如支持native.umask选项：

-
# 启动的容器umask值为0022 
---exec-opt native.umask=normal 
-
-# 启动的容器umask值为0027（默认值）
---exec-opt  native.umask=secure
+
# 启动的容器umask值为0022 --exec-opt native.umask=normal # 启动的容器umask值为0027（默认值）--exec-opt  native.umask=secure

注意如果docker create/run也配置了native.umask参数则以docker create/run中的配置为准。
- - - - - - - - - - - - - - +

ISSUE

-

问题描述

-

I1VR1W

-

使用x86的qcow2镜像创建虚拟机或者使用iso镜像安装物理机在启动时候报错, 实际上是预期内的输出，详情见ISSUE回复内容

-

I1U1LP

-

arm 物理机使用已写入文件系统的磁盘进行自定义分区，分区失败，特殊路径触发可规避，措施见ISSUE回复内容

-

I1VTC5

-

在超分场景压力测试下，vcpu大于1000个时vmtop -H翻页有明显卡顿, 影响范围可控，详情见ISSUE回复内容

-

I1WVM8

-

vmtop收集的cpu使用率，单核使用率存在超过100%的, 影响范围可控，详情见ISSUE回复内容

-
+ + + + + + + + + + + + + + + + + + + + + + + +
+

ISSUE

+ 		+

问题描述

+
+

I1VR1W

+ 		+

使用x86的qcow2镜像创建虚拟机或者使用iso镜像安装物理机在启动时候报错, + 实际上是预期内的输出，详情见ISSUE回复内容

+
+

I1U1LP

+ 		+

arm + 物理机使用已写入文件系统的磁盘进行自定义分区，分区失败，特殊路径触发可规避，措施见ISSUE回复内容

+
+

I1VTC5

+ 		+

在超分场景压力测试下，vcpu大于1000个时vmtop -H翻页有明显卡顿, 影响范围可控，详情见ISSUE回复内容 +

+
+

I1WVM8

+ 		+

vmtop收集的cpu使用率，单核使用率存在超过100%的, 影响范围可控，详情见ISSUE回复内容

+
diff --git "a/docs/zh/docs/20.09/docs/StratoVirt/StratoVrit\350\231\232\346\213\237\345\214\226\347\224\250\346\210\267\346\214\207\345\215\227.md" b/docs/zh/docs/20.09/docs/StratoVirt/StratoVirtGuide.md similarity index 100% rename from "docs/zh/docs/20.09/docs/StratoVirt/StratoVrit\350\231\232\346\213\237\345\214\226\347\224\250\346\210\267\346\214\207\345\215\227.md" rename to docs/zh/docs/20.09/docs/StratoVirt/StratoVirtGuide.md diff --git "a/docs/zh/docs/20.09/docs/Virtualization/\346\234\200\344\275\263\345\256\236\350\267\265.md" "b/docs/zh/docs/20.09/docs/Virtualization/\346\234\200\344\275\263\345\256\236\350\267\265.md" index dd971d0509231d4d0f8bce3adb101f7a8be11977..95af306899812b8c46a8523cce6545a36e8a673f 100644 --- "a/docs/zh/docs/20.09/docs/Virtualization/\346\234\200\344\275\263\345\256\236\350\267\265.md" +++ "b/docs/zh/docs/20.09/docs/Virtualization/\346\234\200\344\275\263\345\256\236\350\267\265.md" @@ -1,23 +1,6 @@ # 最佳实践 - - -- [最佳实践](#最佳实践) - - [性能最佳实践](#性能最佳实践) - - [halt-polling](#halt-polling) - - [IOThread配置](#IOThread配置) - - [裸设备映射](#裸设备映射) - - [kworker隔离绑定](#kworker隔离绑定) - - [内存大页](#内存大页) - - [PV-qspinlock](#PV-qspinlock) - - [Guest-Idle-Haltpoll](#Guest-Idle-Haltpoll) - - [安全最佳实践](#安全最佳实践) - - [Libvirt鉴权](#Libvirt鉴权) - - [qemu-ga](#qemu-ga) - - [sVirt保护](#sVirt保护) - - [虚拟机可信启动](#虚拟机可信启动) - - +[[tod]] ## 性能最佳实践 @@ -296,7 +279,7 @@ Guest-Idle-Haltpoll特性默认关闭，这里给出开启该特性的操作指 - guest\_halt\_poll\_grow\_start: 当系统空闲时，每个vCPU的guest\_halt\_poll\_ns最终会达到零。该参数用于设置当前vCPU guest\_halt\_poll\_ns的初始值，以便vCPU polling时长的收缩和扩展。默认值为50000（单位ns）。 - guest\_halt\_poll\_allow\_shrink: 允许每个vCPU guest\_halt\_poll\_ns收缩的开关，默认值是Y（Y表示允许收缩，N表示禁止收缩）。 - 可以使用root权限，参考如下命令修改参数值。其中_value_表示需要设置的参数值，_configFile_为对应的配置文件。 + 可以使用root权限，参考如下命令修改参数值。其中 _value_ 表示需要设置的参数值， _configFile_ 为对应的配置文件。 ``` # echo value > /sys/module/haltpoll/parameters/configFile diff --git "a/docs/zh/docs/20.09/docs/Virtualization/\347\256\241\347\220\206\347\263\273\347\273\237\350\265\204\346\272\220.md" "b/docs/zh/docs/20.09/docs/Virtualization/\347\256\241\347\220\206\347\263\273\347\273\237\350\265\204\346\272\220.md" index 515df8d8a7cd5e4ab30a073ecfd2692879487413..10e7b920c2a6d66df2800473b97abcb51f9aacd4 100644 --- "a/docs/zh/docs/20.09/docs/Virtualization/\347\256\241\347\220\206\347\263\273\347\273\237\350\265\204\346\272\220.md" +++ "b/docs/zh/docs/20.09/docs/Virtualization/\347\256\241\347\220\206\347\263\273\347\273\237\350\265\204\346\272\220.md" @@ -1,28 +1,16 @@ # 管理系统资源 -使用libvirt命令来管理虚拟机的系统资源，如vCPU、虚拟内存资源等。 +[[tod]] + +## 总体说明 + +openEuler 虚拟化使用libvirt命令来管理虚拟机的系统资源，如vCPU、虚拟内存资源等。 在开始前： - 确保主机上运行了libvirtd守护进程。 - 用virsh list --all命令确认虚拟机已经被定义。 - -- [管理系统资源](#管理系统资源) - - [管理虚拟CPU](#管理虚拟CPU) - - [CPU份额](#CPU份额) - - [绑定QEMU进程至物理CPU](#绑定QEMU进程至物理CPU) - - [调整虚拟CPU绑定关系](#调整虚拟CPU绑定关系) - - [CPU热插](#CPU热插) - - [管理虚拟内存](#管理虚拟内存) - - [NUMA简介](#NUMA简介) - - [配置Host NUMA](#配置Host-NUMA) - - [配置Guest NUMA](#配置Guest-NUMA) - - [内存热插](#内存热插) - - - - ## 管理虚拟CPU diff --git "a/docs/zh/docs/20.09/docs/userguide/\346\246\202\350\277\260.md" b/docs/zh/docs/20.09/docs/userguide/overview.md similarity index 100% rename from "docs/zh/docs/20.09/docs/userguide/\346\246\202\350\277\260.md" rename to docs/zh/docs/20.09/docs/userguide/overview.md diff --git a/docs/zh/docs/20.09/menu/menu.json b/docs/zh/docs/20.09/menu/menu.json index 8764b345574ff336d89abb27b9fa587e8556f029..e68b7b7c63298d10890e021afb0084091d392a6e 100644 --- a/docs/zh/docs/20.09/menu/menu.json +++ b/docs/zh/docs/20.09/menu/menu.json @@ -345,7 +345,7 @@ }, { "label": "StratoVirt虚拟化用户指南", - "path": "docs/StratoVirt/StratoVirt虚拟化用户指南", + "path": "docs/StratoVirt/StratoVirtGuide", "children": [ { "label": "StratoVirt介绍", @@ -373,8 +373,8 @@ "children": [] }, { - "label": "管理虚拟机资源管理", - "path": "docs/StratoVirt/管理虚拟机资源管理", + "label": "管理虚拟机资源", + "path": "docs/StratoVirt/管理虚拟机资源", "children": [] }, { @@ -713,10 +713,10 @@ }, { "label": "openEuler工具集用户指南", - "path": "docs/userguide/概述", + "path": "docs/userguide/overview", "children": [ { - "label": "补丁工具", + "label": "patch-tracking", "path": "docs/userguide/patch-tracking", "children": [] },