Inline HTML header
- ``` - -- **正确示例** - - ```text - # Markdown header - ``` - -### MD034 - 使用纯URL - -- **错误示例** - - ```text - For more information, see http://www.example.com/. - ``` - -- **正确示例** - - ```text - For more information, see**random_forest**: random forest model, which does not support online learning
**vae**: Variational Atuoencoder (VAE), which is an unsupervised model and supports model update based on historical data during the first startup.| -| -d | --duration | int | False | 1 | DURATION | Frequency of executing the exception detection model. The unit is minute, which means that the detection is performed every *x* minutes.| -| -r | --retrain | bool | False | False | RETRAIN | Whether to use historical data to update and iterate the model during startup. Currently, only the VAE model is supported.| -| -l | --look_back | int | False | 4 | LOOK_BACK | Whether to update the model based on the historical data of the last *x* days.| -| -t | --threshold | float | False | 0.8 | THRESHOLD | Threshold of the exception detection model, ranging from 0 to 1. A larger value can reduce the false positive rate of the model. It is recommended that the value be greater than or equal to 0.5.| -| -sli | --sli_time | int | False | 400 | SLI_TIME | Application performance metric. The unit is ms. A larger value can reduce the false positive rate of the model. It is recommended that the value be greater than or equal to 200.
For scenarios with a high false positive rate, it is recommended that the value be greater than 1000.| +Kafka:f + server: "192.168.122.100" + port: "9092" + model_topic: "gala_anteater_hybrid_model" + rca_topic: "gala_cause_inference" + meta_topic: "gala_gopher_metadata" + group_id: "gala_anteater_kafka" + # auth_type: plaintext/sasl_plaintext, please set "" for no auth + auth_type: "" + username: "" + password: "" +Prometheus: + server: "localhost" + port: "9090" + steps: "5" +Aom: + base_url: "" + project_id: "" + auth_type: "token" + auth_info: + iam_server: "" + iam_domain: "" + iam_user_name: "" + iam_password: "" + ssl_verify: 0 -#### Start +Schedule: + duration: 1 +``` -Start gala-anteater. +| Parameter | Description | Default Value | +| ----------- | --------------------------------------------------------------------------------------------- | ---------------------------- | +| Global | | | +| data_source | Data source | "prometheus" | +| Arangodb | | | +| url | IP address of the ArangoDB graph database | "
| Parameter | +Value | +Function | +
|---|---|---|
| ima_appraise | +enforce-evm | +Enforced verification mode of IMA appraisal (EVM enabled) | +
| log-evm | +Log mode of IMA appraisal (EVM enabled) | +|
| enforce | +Enforced verification mode of IMA appraisal | +|
| log | +Log mode of IMA appraisal | +|
| off | +IMA appraisal disabled | +|
| ima_appraise_digest_list | +digest | +IMA+EVM appraisal based on the digest list (comparing file content and extended attributes) | +
| digest-nometadata | +IMA appraisal based on the digest list (comparing file content only) | +|
| evm | +x509 | +Directly enables EVM based on portable signatures (whether or not the EVM certificate is loaded) | +
| complete | +Does not allow modification of EVM mode through the securityfs interface after startup | +|
| allow_metadata_writes | +Allows modification of file metadata without EVM interception | +|
| ima_hash | +sha256/sha1/... | +Declares the IMA measurement hash algorithm | +
| ima_template | +ima | +Declares the IMA measurement template (d|n) | +
| ima-ng | +Declares the IMA measurement template (d-ng|n-ng), which is used by default | +|
| ima-sig | +Declares the IMA measurement template (d-ng|n-ng|sig) | +|
| ima_policy | +exec_tcb | +Measures all executed and memory-mapped files, as well as loaded kernel modules, firmware, and kernel files | +
| tcb | +On the basis of the exec_tcb policy, additionally measures files accessed as uid=0 or euid=0 | +|
| secure_boot | +Evaluates all loaded kernel modules, firmware, and kernel files, and specifies the use of IMA signature mode | +|
| appraise_exec_tcb | +On the basis of the secure_boot policy, additionally evaluates all executed and memory-mapped files | +|
| appraise_tcb | +Evaluates all files accessed with owner 0 | +|
| appraise_exec_immutable | +Used in conjunction with the appraise_exec_tcb policy where the extended attributes of executable files are immutable | +|
| ima_digest_list_pcr | +10 | +Extends the digest list-based IMA measurement results in PCR 10, disabling native IMA measurement | +
| 11 | +Extends the digest list-based IMA measurement results in PCR 11, disabling native IMA measurement | +|
| +11 | +Extends the digest list-based IMA measurement results in PCR 11, extending the native IMA measurement results in PCR 10 | +|
| ima_digest_db_size | +nn[M] | +Sets the upper limit of the kernel digest list size (0 MB to 64 MB). The default is 16 MB if not configured. (Not configured means that the parameter does not present. Note that the value cannot be left blank, such as "ima_digest_db_size=") | +
| ima_capacity | +-1~2147483647 | +Sets the maximum number of kernel measurement log entries. The default is 100,000 if not configured. -1 means no upper limit. | +
| initramtmpfs | +None | +Supports tmpfs in initrd to carry file extended attributes | +
| Option | +Value | +Function | +
|---|---|---|
| -d | +<path> | +Specifies the directory to store the generated digest list files. The value must be a valid directory. | +
| -f | +compact | +Specifies the format of the generated digest list files. Currently, only the compact format is supported. | +
| -i | +<option arg>:<option value> | +Specifies the target file range for generating the digest list. Specific parameter definitions are as follows. | +
| I:<path> | +Specifies the absolute path of the file for which to generate a digest list. If a directory is specified, recursive generation is performed. | +|
| E:<path> | +Specifies the path or directory to exclude. | +|
| F:<path> | +Specifies the path or directory for which to generate digest lists for all files (when the e: parameter is also specified, the filtering effect of the e: option is ignored). | +|
| e: | +Generates a digest list only for executable files. | +|
| l:policy | +Matches file security contexts from the system SELinux policy instead of reading them directly from file extended attributes. | +|
| i: | +When generating a metadata digest list, includes the digest value of the file in the calculated extended attribute information (required). | +|
| M: | +Allows explicitly specifying the file extended attribute information (must be used with the rpmbuild command). | +|
| u: | +Uses the list file name specified by the L: parameter as the file name for generating the digest list (must be used with the rpmbuild command). | +|
| L:<path> | +Specifies the path of the list file, which contains the information data needed to generate the digest list (must be used with the rpmbuild command). | +|
| -o | +add | +Specifies the operation to perform on the generated digest list. Currently, only the add operation is supported, which adds the digest list to the file. | +
| -p | +-1 | +Specifies the position in the file where the digest list is written. Currently, only -1 is supported. | +
| -t | +file | +Generates a digest list only for the file content. | +
| metadata | +Generates separate digest lists for the file content and extended attributes. | +|
| -T | +NA | +If this parameter is not added, a digest list file is generated. If this parameter is added, a TLV digest list file is generated. | +
| -A | +<path> | +Specifies the relative root directory. The file path is truncated with the specified prefix removed for path matching and SELinux label matching. | +
| -m | +immutable | +Specifies the modifiers attribute of the generated digest list file. Currently, only immutable is supported. In enforce/enforce-evm mode, the digest list can only be opened in read-only mode. | +
| -h | +NA | +Prints help information. | +
| Keyword | +Value | +Description | +
|---|---|---|
| action | +measure | +Enables IMA measurement. | +
| dont_measure | +Disables IMA measurement. | +|
| appraise | +Enables IMA appraisal. | +|
| dont_appraise | +Disables IMA appraisal. | +|
| audit | +Enables auditing. | +|
| func | +FILE_CHECK | +File to be opened | +
| MODULE_CHECK | +Kernel module file to be loaded | +|
| MMAP_CHECK | +Shared library file to be mapped to the process memory space | +|
| BRPM_CHECK | +Executable file to be executed (excluding script files opened by programs like /bin/hash) |
+|
| POLICY_CHECK | +IMA policy file to be imported | +|
| FIRMWARE_CHECK | +Firmware to be loaded into memory | +|
| DIGEST_LIST_CHECK | +Digest list file to be loaded into the kernel | +|
| KEXEC_KERNEL_CHECK | +Kernel to be switched to by kexec | +|
| mask | +MAY_EXEC | +Execute file | +
| MAY_WRITE | +Write file | +|
| MAY_READ | +Read file | +|
| MAY_APPEND | +Extend file attributes | +|
| fsmagic | +fsmagic=xxx | +Hexadecimal magic number of the file system type | +
| fsuuid | +fsuuid=xxx | +16-character hexadecimal string of the system device UUID | +
| fowner | +fowner=xxx | +User ID of the file owner | +
| uid | +uid=xxx | +User ID of the user operating on the file | +
| obj_type | +obj_type=xxx_t | +Type of the file (based on SELinux label) | +
| pcr | +pcr= |
+TPM PCR used for extending measurement values (default is 10) | +
| appraise_type | +imasig | +IMA appraisal based on signature | +
| meta_immutable | +Appraisal of file extended attributes based on signature (digest list supported) | +
| Version | +Certificate | +
|---|---|
| openEuler 22.03 LTS | +private OBS b25e7f66 | +
| openEuler 22.03 LTS SP1/2/3 | +private OBS b25e7f66 | +
| openeuler <openeuler@compass-ci.com> b675600b | +|
| openEuler 22.03 LTS SP4 | +private OBS b25e7f66 | +
| openeuler <openeuler@compass-ci.com> b675600b | +|
| openeuler <openeuler@compass-ci.com> fb37bc6f | +|
| openEuler 24.03 LTS | +openEuler kernel ICA 1: 90bb67eb4b57eb62bf6f867e4f56bd4e19e7d041 | +
2. When `opstype` is `upgrade/rollback`, it indicates post-upgrade/rollback configuration, meaning it takes effect after the upgrade/rollback and subsequent reboot. For detailed field descriptions, see the [Settings](#settings). | Required when `opstype` is `config` | + | `upgradeconfigs`| / | Configuration settings to apply before an upgrade. | This parameter is valid for upgrades or rollbacks and takes effect before the upgrade or rollback operation. For detailed field descriptions, see the [Settings](#settings). | Optional | + | `nodeselector` | string | Label of the nodes targeted for the upgrade/configuration/rollback | This parameter is used to perform operations on nodes with specific labels, rather than all worker nodes in the cluster. The nodes targeted for the operation need to have a label with the `upgrade.openeuler.org/node-selector` key. The `nodeselector` parameter should be set to the value of this label. **Notes:** 1. When this parameter is not set or is set to `no-label`, operations are performed on nodes that do not have the `upgrade.openeuler.org/node-selector` label.
2. When this parameter is set to `""` (an empty string), operations are performed on nodes that have the `upgrade.openeuler.org/node-selector=""` label.
3. To ignore labels and perform operations on all nodes, set this parameter to `all-label`. | Optional | + | `timewindow` | / | Time window during which the upgrade/configuration/rollback can take place. | 1. When specifying a time window, both `starttime` and `endtime` must be specified. That is, they should either both be empty or both be non-empty.
1. Both `starttime` and `endtime` are strings and should be in the `YYYY-MM-DD HH:MM:SS` or `HH:MM:SS` format, and both should follow the same format.
2. When in `HH:MM:SS` format, if `starttime` is less than `endtime`, it is assumed that `starttime` refers to that time on the next day.
3. When `timewindow` is not specified, it defaults to no time window restrictions. | Optional | + | `timeinterval` | int | The time interval between each batch of tasks for the upgrade/configuration/rollback operation. | This parameter is in seconds and defines the time interval between the operator dispatching tasks. If the Kubernetes cluster is busy and cannot immediately respond to the operator's request, the actual interval may be longer than the specified time. | Optional | + | `executionmode` | string | The mode in which the upgrade/configuration/rollback operation is executed. | The value can be `serial` or `parallel`. If this parameter is not set, the operation defaults to parallel mode. | Optional | ## Upgrade -Create a custom object of the OS type in the cluster and set the corresponding fields. The OS type comes from the CRD object created in the installation and deployment sections. The following table describes the fields. - -| Parameter |Type | Description | How to Use| Mandatory (Yes/No) | -| -------------- | ------ | ------------------------------------------------------------ | ----- | ---------------- | -| imagetype | string | Type of the upgrade image | The value must be `docker` or `disk`. Other values are invalid. This parameter is valid only in upgrade scenarios.|Yes | -| opstype | string | Operation, that is, upgrade or rollback| The value must be `upgrade` or `rollback`. Other values are invalid.|Yes | -| osversion | string | OS version of the image used for upgrade or rollback | The value must be a KubeOS version, for example, `KubeOS 1.0.0`.|Yes | -| maxunavailable | int | Number of nodes to be upgraded or rolled back at the same time| If the value of `maxunavailable` is greater than the actual number of nodes in the cluster, the deployment can be performed. The upgrade or rollback is performed based on the actual number of nodes in the cluster.|Yes | -| dockerimage | string | Docker image used for upgrade | The value must be in the *repository/name:tag* format. This parameter is valid only when the Docker image is used for upgrade.|Yes | -| imageurl | string | Address of the disk image used for the upgrade| `imageurl` contains the protocol and only HTTP or HTTPS is supported. For example, `https://192.168.122.15/update.img` is valid only when a disk image is used for upgrade.|Yes | -| checksum | string | Checksum (SHA-256) value for disk image verification during the upgrade. | This parameter is valid only when a disk image is used for upgrade.|Yes | -| flagSafe | bool | Whether `imageurl` specifies a secure HTTP address | The value must be `true` or `false`. This parameter is valid only when `imageurl` specifies an HTTP address.|Yes | -| mtls | bool | Whether HTTPS two-way authentication is used for the connection to the `imageurl` address. | The value must be `true` or `false`. This parameter is valid only when `imageurl` specifies an HTTPS address.|Yes | -| cacert | string | Root certificate file used for HTTPS or HTTPS two-way authentication | This parameter is valid only when `imageurl` specifies an HTTPS address.| This parameter is mandatory when `imageurl` specifies an HTTPS address.| -| clientcert | string | Client certificate file used for HTTPS two-way authentication | This parameter is valid only when HTTPS two-way authentication is used.|This parameter is mandatory when `mtls` is set to `true`.| -| clientkey | string | Client public key used for HTTPS two-way authentication | This parameter is valid only when HTTPS two-way authentication is used.|This parameter is mandatory when `mtls` is set to `true`.| - -The address specified by `imageurl` contains the protocol. Only the HTTP or HTTPS protocol is supported. If `imageurl` is set to an HTTPS address, secure transmission is used. If `imageurl` is set to an HTTP address, set `flagSafe` to `true`, because the image can be downloaded only when the address is secure. If `imageurl` is set to an HTTP address but `flagSafe` is not set to `true`, the address is insecure by default. The image will not be downloaded, and a message is written to the log of the node to be upgraded indicating that the address is insecure. - -You are advised to set `imageurl` to an HTTPS address. In this case, ensure that the required certificate has been installed on the node to be upgraded. If the image server is maintained by yourself, you need to sign the certificate and ensure that the certificate has been installed on the node to be upgraded. Place the certificate in the **/etc/KubeOS/certs** directory of KubeOS. The administrator specifies the address and must ensure the security of the address. An intranet address is recommended. - -The container OS image provider must check the validity of the image to ensure that the downloaded container OS image is from a reliable source. - -Compile the YAML file for deploying the OS as a custom resource (CR) instance in the cluster. The following is an example YAML file for deploying the CR instance: - -- Upgrade using a disk image - - ``` - apiVersion: upgrade.openeuler.org/v1alpha1 - kind: OS - metadata: - name: os-sample - spec: - imagetype: disk - opstype: upgrade - osversion: edit.os.version - maxunavailable: edit.node.upgrade.number - dockerimage: "" - imageurl: edit.image.url - checksum: image.checksum - flagSafe: imageurl.safety - mtls: imageurl use mtls or not - cacert: ca certificate - clientcert: client certificate - clientkey: client certificate key - ``` - -- Upgrade using a Docker image - - ``` shell - apiVersion: upgrade.openeuler.org/v1alpha1 - kind: OS - metadata: - name: os-sample - spec: - imagetype: docker - opstype: upgrade - osversion: edit.os.version - maxunavailable: edit.node.upgrade.number - dockerimage: dockerimage like repository/name:tag - imageurl: "" - checksum: "" - flagSafe: false - mtls: true - ``` - - Before using a Docker image to perform the upgrade, create the image first. For details about how to create a Docker image, see **KubeOS Image Creation**. - -Assume that the YAML file is **upgrade_v1alpha1_os.yaml**. - -Check the OS version of the node that is not upgraded. - -``` -kubectl get nodes -o custom-columns='NAME:.metadata.name,OS:.status.nodeInfo.osImage' -``` - -Run the following command to deploy the CR instance in the cluster. The node is upgraded based on the configured parameters. - -``` -kubectl apply -f upgrade_v1alpha1_os.yaml -``` - -Check the node OS version again to determine whether the node upgrade is complete. - -``` -kubectl get nodes -o custom-columns='NAME:.metadata.name,OS:.status.nodeInfo.osImage' -``` - -> **NOTE**: -> -> If you need to perform the upgrade again, modify the `imageurl`, `osversion`, `checksum`, `maxunavailable`, `flagSafe`, or `dockerimage` parameters in **upgrade_v1alpha1_os.yaml**. - -## Rollback - -### Application Scenarios +1. Create a YAML file and deploy an instance of the OS Custom Resource (CR) in the cluster. This YAML file defines the upgrade process. The following example assumes you save the YAML content to **upgrade_v1alpha1_os.yaml**. + + - Upgrade using a drive image + + ```yaml + apiVersion: upgrade.openeuler.org/v1alpha1 + kind: OS + metadata: + name: os-sample + spec: + imagetype: disk + opstype: upgrade + osversion: edit.os.version + maxunavailable: edit.node.upgrade.number + containerimage: "" + evictpodforce: true/false + imageurl: edit.image.url + checksum: image.checksum + flagSafe: imageurl.safety + mtls: imageurl use mtls or not + cacert: ca certificate + clientcert: client certificate + clientkey: client certificate key + ``` + + - Upgrade using a container image + - Before you can upgrade using a container image, you need to create a container image specifically for the upgrade process. For detailed instructions on how to create this image, see [KubeOS OCI 镜像制作](./kubeos-image-creation.md#creating-a-kubeos-oci-image) in [KubeOS Image Creation](./kubeos-image-creation.md). + + ``` yaml + apiVersion: upgrade.openeuler.org/v1alpha1 + kind: OS + metadata: + name: os-sample + spec: + imagetype: docker + opstype: upgrade + osversion: edit.os.version + maxunavailable: edit.node.upgrade.number + containerimage: container image like repository/name:tag + evictpodforce: true/false + imageurl: "" + checksum: container image digests + flagSafe: false + mtls: true + ``` + + - Using containerd as the container engine + + ```yaml + apiVersion: upgrade.openeuler.org/v1alpha1 + kind: OS + metadata: + name: os-sample + spec: + imagetype: containerd + opstype: upgrade + osversion: edit.os.version + maxunavailable: edit.node.upgrade.number + containerimage: container image like repository/name:tag + evictpodforce: true/false + imageurl: "" + checksum: container image digests + flagSafe: false + mtls: true + ``` + + - Example of upgrading and applying configurations + - This example uses containerd as the container engine. The upgrade method does not affect the configuration process. `upgradeconfigs` are applied before the upgrade. `sysconfigs` are applied after the machine reboots from the upgrade. See [Settings](#settings) for detailed information about the configuration parameters. + - When upgrading and configuring, set the `opstype` field to `upgrade`. + + ```yaml + apiVersion: upgrade.openeuler.org/v1alpha1 + kind: OS + metadata: + name: os-sample + spec: + imagetype: "" + opstype: upgrade + osversion: edit.os.version + maxunavailable: edit.node.upgrade.number + containerimage: "" + evictpodforce: true/false + imageurl: "" + checksum: container image digests + flagSafe: false + mtls: false + sysconfigs: + version: edit.os.version + configs: + - model: kernel.sysctl + contents: + - key: kernel param key1 + value: kernel param value1 + - key: kernel param key2 + value: kernel param value2 + - model: kernel.sysctl.persist + configpath: persist file path + contents: + - key: kernel param key3 + value: kernel param value3 + - key: "" + value: "" + upgradeconfigs: + version: 1.0.0 + configs: + - model: kernel.sysctl + contents: + - key: kernel param key4 + value: kernel param value4 + ``` + + - Example of upgrading specific nodes using `nodeselector`, `timewindow`, `timeinterval`, and `executionmode` + - This example uses containerd as the container engine. The upgrade method does not affect node selection. + - Nodes targeted for upgrade must include the `upgrade.openeuler.org/node-selector` label. The value of `nodeselector` in the YAML file should match the value of this label on the desired nodes. For example, if `nodeselector` is set to `kubeos`, only worker nodes with the `upgrade.openeuler.org/node-selector=kubeos` label will be upgraded. + - `nodeselector`, `timewindow`, `timeinterval`, and `executionmode` are also applicable to configuration and rollback operations. + - Example commands for managing node labels: + + ``` shell + # Add a label to node kubeos-node1 + kubectl label nodes kubeos-node1 upgrade.openeuler.org/node-selector=kubeos-v1 + # Modify the label of node kubeos-node1 + kubectl label --overwrite nodes kubeos-node1 upgrade.openeuler.org/node-selector=kubeos-v2 + # Delete the label from node kubeos-node1 + kubectl label nodes kubeos-node1 upgrade.openeuler.org/node-selector- + # View the labels of all nodes + kubectl get nodes --show-labels + ``` + + - Example YAML file: + + ```yaml + apiVersion: upgrade.openeuler.org/v1alpha1 + kind: OS + metadata: + name: os-sample + spec: + imagetype: containerd + opstype: upgrade + osversion: edit.os.version + maxunavailable: edit.node.upgrade.number + containerimage: container image like repository/name:tag + evictpodforce: true/false + imageurl: "" + checksum: container image digests + flagSafe: false + mtls: true + nodeselector: edit.node.label.key + timewindow: + starttime: "HH::MM::SS/YYYY-MM-DD HH::MM::SS" + endtime: "HH::MM::SS/YYYY-MM-DD HH::MM::SS" + timeinterval: time intervel like 30 + executionmode: serial/parallel + ``` + +2. Check the OS version of nodes that have not been upgraded. + + ```shell + kubectl get nodes -o custom-columns='NAME:.metadata.name,OS:.status.nodeInfo.osImage' + ``` -- If a node cannot be started, you can only manually roll back the container OS to the previous version that can be properly started. -- If a node can be started and run the system, you can manually or use KubeOS (similar to the upgrade) to roll back the container OS. You are advised to use KubeOS. +3. Deploy the CR instance in the cluster. Nodes will be upgraded based on the parameters specified in the YAML file. -### Manual Rollback + ```shell + kubectl apply -f upgrade_v1alpha1_os.yaml + ``` -Manually restart the node and select the second boot option to roll back the container OS. Manual rollback can only roll back the container OS to the version before the upgrade. +4. Check the OS version of the nodes again to confirm if the upgrade is complete. -### KubeOS-based Rollback + ```shell + kubectl get nodes -o custom-columns='NAME:.metadata.name,OS:.status.nodeInfo.osImage' + ``` -- Roll back to any version. - - Modify the YAML configuration file (for example, **upgrade_v1alpha1_os.yaml**) of the CR instance of the OS and set the corresponding fields to the image information of the target source version. The OS type comes from the CRD object created in the installation and deployment sections. For details about the fields and examples, see the previous section. +5. If you need to perform the upgrade again, modify the corresponding fields in **upgrade_v1alpha1_os.yaml**. - - After the YAML is modified, run the update command. After the custom object is updated in the cluster, the node performs rollback based on the configured field information. +> **Note:** +> +> If you need to perform the upgrade again, modify the `imageurl`, `osversion`, `checksum`, `maxunavailable`, `flagSafe`, or `dockerimage` parameters in **upgrade_v1alpha1_os.yaml**. - ``` - kubectl apply -f upgrade_v1alpha1_os.yaml - ``` +## Settings -- Roll back to the previous version. +- Settings parameters - - Modify the **upgrade_v1alpha1_os.yaml** file. Set **osversion** to the previous version and **opstype** to **rollback** to roll back to the previous version (that is, switch to the previous partition). Example YAML: + This section describes the configuration parameters using an example YAML file. Your configuration should follow the same indentation as the example: - ``` + ```yaml apiVersion: upgrade.openeuler.org/v1alpha1 kind: OS metadata: - name: os-sample + name: os-sample spec: - imagetype: "" - opstype: rollback - osversion: KubeOS pervious version - maxunavailable: 2 - dockerimage: "" - imageurl: "" - checksum: "" - flagSafe: false - mtls:true + imagetype: "" + opstype: config + osversion: edit.os.version + maxunavailable: edit.node.config.number + containerimage: "" + evictpodforce: false + checksum: "" + sysconfigs: + version: edit.sysconfigs.version + configs: + - model: kernel.sysctl + contents: + - key: kernel param key1 + value: kernel param value1 + - key: kernel param key2 + value: kernel param value2 + operation: delete + - model: kernel.sysctl.persist + configpath: persist file path + contents: + - key: kernel param key3 + value: kernel param value3 + - model: grub.cmdline.current + contents: + - key: boot param key1 + - key: boot param key2 + value: boot param value2 + - key: boot param key3 + value: boot param value3 + operation: delete + - model: grub.cmdline.next + contents: + - key: boot param key4 + - key: boot param key5 + value: boot param value5 + - key: boot param key6 + value: boot param value6 + operation: delete ``` - - After the YAML is modified, run the update command. After the custom object is updated in the cluster, the node performs rollback based on the configured field information. + Configuration parameters + + | Parameter | Type | Description | Usage Note | Mandatory | + | ---------- | -------- | --------------------------- | ------------------------------------------------------------ | ----------------------- | + | `version` | string | Configuration version | This parameter determines if the configuration should be applied by comparing versions. If `version` is empty (`""` or not set), the comparison will still be performed. Therefore, if `sysconfigs` or `upgradeconfigs` is not configured, the existing `version` will be cleared, triggering the configuration. | Yes | + | `configs` | / | Specific configuration content | This parameter contains a list of specific configuration items. | Yes | + | `model` | string | Configuration type | See the [Settings List](#settings-list) in the appendix for supported configuration types. | Yes | + | `configpath` | string | Configuration file path | This parameter is only effective for the `kernel.sysctl.persist` configuration type. See the [Settings List](#settings-list) in the appendix for the description of the configuration file path. | No | + | `contents` | / | Specific key/value pairs and operation type | This parameter contains a list of specific configuration items. | Yes | + | `key` | string | Parameter name | `key` cannot be empty or contain `=`. You are advised not to configure strings containing spaces or tabs. For specific usage of `key` for each configuration type, see the [Settings List](#settings-list) in the appendix. | Yes | + | `value` | string | Parameter value | `value` cannot be empty for parameters in the `key=value` format. You are advised not to configure strings containing spaces or tabs. For specific usage of `value` for each configuration type, see the [Settings List](#settings-list) in the appendix. | Required for parameters in the `key=value` format | + | `operation` | string | Operation to be performed on the parameter | This parameter is only effective for `kernel.sysctl.persist`, `grub.cmdline.current`, and `grub.cmdline.next` parameter types. The default behavior is to add or update. The value can only be `delete`, which means deleting the existing parameter (the `key=value` must match exactly for deletion). | No | + - `upgradeconfigs` has the same parameters as `sysconfigs`. `upgradeconfigs` is for configuration before upgrade/rollback and only takes effect in upgrade/rollback scenarios. `sysconfigs` supports both configuration only and configuration after upgrade/rollback reboot. + +- Usage + + 1. Create a YAML file like the **upgrade_v1alpha1_os.yaml** example above and deploy the OS CR instance in the cluster. + + 2. Check the configuration version and node status before applying the configuration (`NODESTATUS` should be `idle`). + + ```shell + kubectl get osinstances -o custom-columns='NAME:.metadata.name,NODESTATUS:.spec.nodestatus,SYSCONFIG:status.sysconfigs.version,UPGRADECONFIG:status.upgradeconfigs.version' + ``` + + 3. Apply the configuration, then check the node status again (`NODESTATUS` should change to `config`). + + ```shell + kubectl apply -f upgrade_v1alpha1_os.yaml + kubectl get osinstances -o custom-columns='NAME:.metadata.name,NODESTATUS:.spec.nodestatus,SYSCONFIG:status.sysconfigs.version,UPGRADECONFIG:status.upgradeconfigs.version' + ``` + + 4. Check the node configuration version again to confirm whether the configuration is complete (`NODESTATUS` should return to `idle`): + + ```shell + kubectl get osinstances -o custom-columns='NAME:.metadata.name,NODESTATUS:.spec.nodestatus,SYSCONFIG:status.sysconfigs.version,UPGRADECONFIG:status.upgradeconfigs.version' + ``` + +- If you need to perform the configuration again, modify the corresponding fields in **upgrade_v1alpha1_os.yaml**. + +## Rollback + +- Scenarios + - When a VM fails to start, you can manually select the previous version from the GRUB boot menu. This method only supports rollback to the previous version. + - When a VM starts successfully and you can access the system, you can use the rollback tool (recommended) or manually select the previous version from the GRUB boot menu. + - You can use the rollback tool in two ways: + 1. Rollback mode: reverts to the previous version. + 2. Upgrade mode: re-upgrades to the previous version. +- Manual rollback instructions + - Restart the VM and select the second boot option in the GRUB boot menu to roll back to the previous version. +- Rollback tool instructions + - Rolling back to any version + 1. Modify the YAML configuration file of the OS CR instance (for example, **upgrade_v1alpha1_os.yaml**). Set the relevant fields to the image information of the desired version. The OS category originates from the CRD object created in the installation and deployment document. Refer to the upgrade instructions in the previous section for field descriptions and examples. + + 2. After modifying the YAML file, execute the update command. Nodes will then roll back according to the configured field information. + + ```shell + kubectl apply -f upgrade_v1alpha1_os.yaml + ``` + + - Rolling back to the previous version + - To roll back to the previous OS version, modify the **upgrade_v1alpha1_os.yaml** file. Set `osversion` to the previous version and `opstype` to `rollback` to roll back to the previous version (that is, switch to the previous partition). Example YAML file: + + ```yaml + apiVersion: upgrade.openeuler.org/v1alpha1 + kind: OS + metadata: + name: os-sample + spec: + imagetype: "" + opstype: rollback + osversion: KubeOS pervious version + maxunavailable: 2 + containerimage: "" + evictpodforce: true/false + imageurl: "" + checksum: "" + flagSafe: false + mtls: true + ``` + + - To roll back to the previous configuration version (note that already configured parameters cannot be rolled back), modify the `upgrade_v1alpha1_os.yaml` file. Set `version` of `sysconfigs/upgradeconfigs` to the previous version. Example YAML file: + + ```yaml + apiVersion: upgrade.openeuler.org/v1alpha1 + kind: OS + metadata: + name: os-sample + spec: + imagetype: "" + opstype: config + osversion: edit.os.version + maxunavailable: edit.node.config.number + containerimage: "" + evictpodforce: true/false + imageurl: "" + checksum: "" + flagSafe: false + mtls: false + sysconfigs: + version: previous config version + configs: + - model: kernel.sysctl + contents: + - key: kernel param key1 + value: kernel param value1 + - key: kernel param key2 + value: kernel param value2 + - model: kernel.sysctl.persist + configpath: persist file path + contents: + - key: kernel param key3 + value: kernel param value3 + ``` + + 3. After modifying the YAML file and executing the update command, the nodes will roll back based on the configured information. + + ```shell + kubectl apply -f upgrade_v1alpha1_os.yaml + ``` + + 4. Verify that the rollback was successful. + - To check the container OS version (for OS version rollback), verify container OS version of the node. + - To check the configuration version (for configuration rollback), verify the node configuration version and that the node status is `idle`. + + ```shell + kubectl get osinstances -o custom-columns='NAME:.metadata.name,NODESTATUS:.spec.nodestatus,SYSCONFIG:status.sysconfigs.version,UPGRADECONFIG:status.upgradeconfigs.version' + ``` + +## Appendixes + +### Settings List + +#### kernel Settings + +- `kernel.sysctl`: temporarily sets kernel parameters. These settings will be lost after a reboot. The key/value pairs represent key/value pairs of kernel parameters. Both keys and values cannot be empty. Keys cannot contain the `=` character. The value of `operation` cannot be `delete`. Example: + + ```yaml + configs: + - model: kernel.sysctl + contents: + - key: user.max_user_namespaces + value: 16384 + - key: net.ipv4.tcp_tw_recycle + value: 0 + operation: delete ``` - kubectl apply -f upgrade_v1alpha1_os.yaml + +- `kernel.sysctl.persist`: sets persistent kernel parameters that will be retained after a reboot. The key/value pairs represent key/value pairs of kernel parameters. Both keys and values cannot be empty. Keys cannot contain the `=` character. `configpath` specifies the path to the configuration file, which can be a new file (given that the parent directory exists). If not specified, it defaults to **/etc/sysctl.conf**. Example: + + ```yaml + configs: + - model: kernel.sysctl.persist + configpath : /etc/persist.conf + contents: + - key: user.max_user_namespaces + value: 16384 + - key: net.ipv4.tcp_tw_recycle + value: 0 + operation: delete ``` - After the update is complete, the node rolls back the container OS based on the configuration information. +#### GRUB Settings + +- `grub.cmdline.current/next`: sets the kernel boot parameters in the **grub.cfg** file. These parameters appear on the line resembling the following example in **grub.cfg**: -- Check the OS version of the container on the node to determine whether the rollback is successful. + ```text + linux /boot/vmlinuz root=/dev/sda2 ro rootfstype=ext4 nomodeset quiet oops=panic softlockup_panic=1 nmi_watchdog=1 rd.shell=0 selinux=0 crashkernel=256M panic=3 + ``` - ``` - kubectl get nodes -o custom-columns='NAME:.metadata.name,OS:.status.nodeInfo.osImage' - ``` + - The `grub.cmdline.current/next` settings allow configuration for either the current or the next partition: + + - `grub.cmdline.current`: Configures the boot parameters for the current partition. + - `grub.cmdline.next`: Configures the boot parameters for the next partition. + + - Note: During upgrades/rollbacks, the `current` and `next` partition designations in the configuration (`sysconfigs`) are determined at the time the upgrade/rollback operation is initiated. For instance, if the current partition is `A` and an upgrade is initiated with `grub.cmdline.current` configured in `sysconfigs`, the configuration will still be applied to partition `A` after the reboot, even though it may no longer be the `current` partition. + + - `grub.cmdline.current/next` supports both `key=value` (where `value` cannot be empty) and single `key` formats. If `value` contains an equal sign (for example, `root=UUID=some-uuid`), `key` should be set to all characters before the first `=` and `value` should be set to all characters after the first `=`. Example: + + ```yaml + configs: + - model: grub.cmdline.current + contents: + - key: selinux + value: "0" + - key: root + value: UUID=e4f1b0a0-590e-4c5f-9d8a-3a2c7b8e2d94 + - key: panic + value: "3" + operation: delete + - key: crash_kexec_post_notifiers + - model: grub.cmdline.next + contents: + - key: selinux + value: "0" + - key: root + value: UUID=e4f1b0a0-590e-4c5f-9d8a-3a2c7b8e2d94 + - key: panic + value: "3" + operation: delete + - key: crash_kexec_post_notifiers + ``` diff --git a/docs/en/docs/SecHarden/file-permissions.md b/docs/en/docs/SecHarden/file-permissions.md index 62925c84449cc2c3bf75485b33abf4ee47206147..eaee0cb7a3f59b3cb970a7bf89d015934f036e16 100644 --- a/docs/en/docs/SecHarden/file-permissions.md +++ b/docs/en/docs/SecHarden/file-permissions.md @@ -221,7 +221,7 @@ The **cron** command is used to create a routine task. Users who can run the ### Description -A common user can use the **sudo** command to run commands as the user **root**. To harden system security, it is necessary to restrict permissions on the **sudo** command. Only user **root** can use the **sudo** command. By default, openEuler does not retrict the permission of non-root users to run the sudo command. +A common user can use the **sudo** command to run commands as the user **root**. To harden system security, it is necessary to restrict permissions on the **sudo** command. Only user **root** can use the **sudo** command. By default, openEuler does not restrict the permission of non-root users to run the sudo command. ### Implementation diff --git a/docs/en/docs/StratoVirt/VM_configuration.md b/docs/en/docs/StratoVirt/VM_configuration.md index b705276e53e7a8c4758e91f4045098953238419f..72170ecfb81206f635507287db1746cbcdf6e040 100644 --- a/docs/en/docs/StratoVirt/VM_configuration.md +++ b/docs/en/docs/StratoVirt/VM_configuration.md @@ -679,8 +679,8 @@ This section provides an example of the minimum configuration for creating a sta $ /path/to/stratovirt \ -kernel /path/to/vmlinux.bin \ -append console=ttyAMA0 root=/dev/vda rw reboot=k panic=1 \ - -drive file=/path/to/code_storage_file,if=pflash,unit=0[,readonly=true] \ - -drive file=/path/to/data_storage_file,if=pfalsh,unit=1, \ + -drive file=/path/to/edk2/code_storage_file,if=pflash,unit=0[,readonly=true] \ + -drive file=/path/to/edk2/data_storage_file,if=pflash,unit=1, \ -drive file=/home/rootfs.ext4,id=rootfs,readonly=false \ -device virtio-blk-device,drive=rootfs,bus=pcie.0,addr=0x1 \ -qmp unix:/tmp/stratovirt.socket,server,nowait \ diff --git a/docs/en/docs/Virtualization/Skylark.md b/docs/en/docs/Virtualization/Skylark.md index b844683707094f67ee57b094595aa48cb9612b3d..6528aeb5c97d4aa7970e868557bfef731c6ecd8d 100644 --- a/docs/en/docs/Virtualization/Skylark.md +++ b/docs/en/docs/Virtualization/Skylark.md @@ -127,7 +127,7 @@ After the Skylark component is installed, you can modify the configuration file Skylark's interference control on LLC/MB depends on the RDT/MPAM function provided by hardware. For Intel x86_64 processors, **rdt=cmt,mbmtotal,mbmlocal,l3cat,mba** needs to be added to kernel command line parameters. For Kunpeng920 processors, **mpam=acpi** needs to be added to kernel command line parameters. -- **MIN_LLC_WAYS_LOW_VMS** is an integer used to control the number of LLC ways that can be accessed by low-priority VMs. The value ranges from 1 to 3, with the default value being 2. During initialization, Skylark limits the numfer of accessible LLC ways for low-priority VMs to this value. +- **MIN_LLC_WAYS_LOW_VMS** is an integer used to control the number of LLC ways that can be accessed by low-priority VMs. The value ranges from 1 to 3, with the default value being 2. During initialization, Skylark limits the number of accessible LLC ways for low-priority VMs to this value. - **MIN_MBW_LOW_VMS** is a floating point number used to control the memory bandwidth ratio available to low-priority VMs. The value ranges from 0.1 to 0.2, with the default value being 0.1. Skylark limits the memory bandwidth of low-priority VMs based on this value during initialization. diff --git a/docs/en/docs/Virtualization/environment-preparation.md b/docs/en/docs/Virtualization/environment-preparation.md index b9c39a0897156e257aca2b00c1e628b2fb393ce5..60e4deb98481479f30484321e76b7569e079e845 100644 --- a/docs/en/docs/Virtualization/environment-preparation.md +++ b/docs/en/docs/Virtualization/environment-preparation.md @@ -110,9 +110,6 @@ To enable the VM to communicate with external networks, you need to configure th This section describes how to set up a Linux bridge and an Open vSwitch bridge to connect a VM to the network. You can select a bridge type based on the site requirements. -**Figure 1** Virtual network structure - - ### Setting Up a Linux Bridge The following describes how to bind the physical NIC eth0 to the Linux bridge br0. @@ -245,6 +242,10 @@ The following describes how to set up an Open vSwitch layer-1 bridge br0. ``` 4. Assign an IP address to OVS bridge br0. + + >  **illustrate：** + > + > If you use DHCP to set a dynamic IP address for br0, you need to clear the existing dynamic IP address. Run the dhclient -r command to clear the possible dynamic IP addresses. - If a DHCP server is available, set a dynamic IP address through the dhclient. ```shell diff --git a/docs/en/docs/desktop/Gnome_userguide.md b/docs/en/docs/desktop/Gnome_userguide.md index a18db4f7bd5820047eb680dd25da7f9e9e412f0f..ac254c0a8dcdf5e7835ff71fd7fc6bfa31cac351 100644 --- a/docs/en/docs/desktop/Gnome_userguide.md +++ b/docs/en/docs/desktop/Gnome_userguide.md @@ -90,7 +90,7 @@ If there are so many apps and you know their names, you can enter an app name in #### 3.1.3 List of Active Apps -Active apps, that is, running apps are displayed one by one after the last app in **Favorites**. There is a white dot under each active app. +Active apps, that is, running apps are displayed one by one after the last app in **Favorites**. There is a white dot under the icon of each active app.  diff --git a/docs/en/docs/memsafety/utshell/utshell_guide.md b/docs/en/docs/memsafety/utshell/utshell_guide.md index 77f6d2ed3b85610ea8acc2fd3fbb33e64c210fd0..b722699436ab3eda88c54ef1460d2cefbf8addd8 100644 --- a/docs/en/docs/memsafety/utshell/utshell_guide.md +++ b/docs/en/docs/memsafety/utshell/utshell_guide.md @@ -181,7 +181,7 @@ done **{1..500..2}** indicates that the start number is 1, the end number is 500 (included), and the step is 2. -#### util +#### until ```shell until [condition]; do diff --git a/docs/en/docs/oeDeploy/Introduction.md b/docs/en/docs/oeDeploy/Introduction.md new file mode 100644 index 0000000000000000000000000000000000000000..aa9d11c0507f077a68f3000b7eac810808bb5f22 --- /dev/null +++ b/docs/en/docs/oeDeploy/Introduction.md @@ -0,0 +1,3 @@ +# Introduction + +The current document has not been written yet. Please refer to the [Chinese document](../../../zh/docs/oeDeploy/Introduction.md). diff --git a/docs/en/docs/ops_guide/information-collection.md b/docs/en/docs/ops_guide/information-collection.md index 2f2c8d036bfc55d89e966667e1d56a683140416d..3b2d7e31a29bed9e79c94851e82a155c547459ea 100644 --- a/docs/en/docs/ops_guide/information-collection.md +++ b/docs/en/docs/ops_guide/information-collection.md @@ -115,7 +115,7 @@ 4. View the file list of a software package. ```shell - rpm -ql python3-rpm # (python3-rpm is used as an emple.) + rpm -ql python3-rpm # (python3-rpm is used as an example.) ``` ## Viewing OS Logs diff --git a/docs/en/docs/secGear/introduction-to-secGear.md b/docs/en/docs/secGear/introduction-to-secGear.md index aa0bc3a4db74c44bdcc2b3fcaf777e1070e79c41..04faa00a5345a2b85a4e0b92b938a231b8f3b5c9 100644 --- a/docs/en/docs/secGear/introduction-to-secGear.md +++ b/docs/en/docs/secGear/introduction-to-secGear.md @@ -34,14 +34,15 @@ Switchless is a technology that uses shared memory to reduce the number of conte ```c typedef struct { - uint32_t num_uworkers; - uint32_t num_tworkers; - uint32_t switchless_calls_pool_size; - uint32_t retries_before_fallback; - uint32_t retries_before_sleep; - uint32_t parameter_num; - uint32_t workers_policy; - uint32_t rollback_to_common; + uint32_t num_uworkers; + uint32_t num_tworkers; + uint32_t switchless_calls_pool_size; + uint32_t retries_before_fallback; + uint32_t retries_before_sleep; + uint32_t parameter_num; + uint32_t workers_policy; + uint32_t rollback_to_common; + cpu_set_t num_cores; } cc_sl_config_t; ``` @@ -55,8 +56,9 @@ Switchless is a technology that uses shared memory to reduce the number of conte | parameter_num | Maximum number of parameters supported by a switchless function. This field takes effect only on the Arm platform.
Specifications:
Arm: maximum value: **16**; minimum value: **0**.| | workers_policy | Running mode of the switchless proxy thread. This field takes effect only on the Arm platform.
Specifications:
Arm:
**WORKERS_POLICY_BUSY**: The proxy thread always occupies CPU resources regardless of whether there are tasks to be processed. This mode applies to scenarios that require high performance and extensive system software and hardware resources.
**WORKERS_POLICY_WAKEUP**: The proxy thread wakes up only when there is a task. After the task is processed, the proxy thread enters the sleep state and waits to be woken up by a new task.| | rollback_to_common | Whether to roll back to a common call when an asynchronous switchless call fails. This field takes effect only on the Arm platform.
Specifications:
Arm:
**0**: No. If the operation fails, only the error code is returned.
Other values: Yes. If the operation fails, an asynchronous switchless call is rolled back to a common call and the return value of the common call is returned.| + | num_cores | Cores for binding processes in the REE. The maximum value is number of CPU cores. | -2. Add the **transition_using_threads** flag when defining the API in the enclave description language (EDL) file. +1. Add the **transition_using_threads** flag when defining the API in the enclave description language (EDL) file. ```ocaml enclave { @@ -82,7 +84,8 @@ A secure channel is a technology that combines confidential computing remote att #### How to Use -The secure channel is provided as a library and consists of the client, host, and enclave, which are icalled by the client, server client application (CA), and server trusted application (TA) of the service program respectively. +The secure channel is provided as a library and consists of the client, host, and enclave, which are called by the client, server client application (CA), and server trusted application (TA) of the service program respectively. + | Module | Header File | Library File | Dependency | |------------|--------------------------|-----------------------|---------| | Client | secure_channel_client.h | libcsecure_channel.so | OpenSSL| @@ -110,10 +113,54 @@ The secure channel is provided as a library and consists of the client, host, an A secure channel encapsulates only the key negotiation process and encryption and decryption APIs, but does not establish any network connection. The negotiation process reuses the network connection of the service. The network connection between the client and server is established and maintained by the service. The message sending hook function and network connection pointer are transferred during the initialization of the secure channel on the client and the server. For details, see [secure channel examples](https://gitee.com/openeuler/secGear/tree/master/examples/secure_channel). +## Remote Attestation + +### Customer Pain Points + +With the development of confidential computing technology, several mainstream technologies have emerged, including Arm TrustZone/CCA, Intel SGX/TDX, QingTian Enclave, and Hygon CSV. Product solutions may involve multiple confidential computing hardware and even collaboration between different TEEs. Remote attestation is a crucial part of the trust chain for any confidential computing technology. However, each technology has its own format for remote attestation reports and verification processes. Users need to integrate different verification processes for different TEE attestation reports, which increases integration burdens and hinders the expansion of new TEE types. + +### Solution + +The unified remote attestation framework of secGear addresses the key components related to remote attestation in confidential computing, abstracting away the differences between different TEEs. It provides two components: attestation agent and attestation service. The agent is integrated by users to obtain attestation reports and connect to the attestation service. The service can be deployed independently and supports the verification of iTrustee and virtCCA remote attestation reports. + +### Features + +The unified remote attestation framework focuses on confidential computing functionalities, while service deployment and operation capabilities are provided by third-party deployment services. The key features of the unified remote attestation framework are as follows: + +- Report verification plugin framework: Supports runtime compatibility with attestation report verification for different TEE platforms, such as iTrustee, virtCCA, and CCA. It also supports the extension of new TEE report verification plugins. +- Certificate baseline management: Supports the management of TCB/TA baseline values and public key certificates for different TEE types. Centralized deployment on the server ensures transparency for users. +- Policy management: Provides default policies for ease of use and customizable policies for flexibility. +- Identity token: Issues identity tokens for different TEEs, endorsed by a third party for mutual authentication between different TEE types. +- Attestation agent: Supports connection to attestation service/peer-to-peer attestation, compatible with TEE report retrieval and identity token verification. It is easy to integrate, allowing users to focus on their service logic. + +Two modes are supported depending on the usage scenario: Peer-to-peer verification and attestation service verification. + +Attestation service verification process: + +1. The user (regular node or TEE) initiates a challenge to the TEE platform. +2. The TEE platform obtains the TEE attestation report through the attestation agent and returns it to the user. +3. The user-side attestation agent forwards the report to the remote attestation service. +4. The remote attestation service verifies the report and returns a unified format identity token endorsed by a third party. +5. The attestation agent verifies the identity token and parses the attestation report verification result. +6. Once the verification passes, a secure connection is established. + +Peer-to-peer verification process (without the attestation service): + +1. The user initiates a challenge to the TEE platform, and the TEE platform returns the attestation report to the user. +2. The user uses a local peer-to-peer TEE verification plugin to verify the report. + +>  **Note:** +> +> The attestation agents used for peer-to-peer verification and attestation service verification are different. During compilation, the compilation options determine whether to compile attestation agents for attestation service mode or peer-to-peer mode. + +### Application Scenarios + +In scenarios like finance and AI, where confidential computing is used to protect the security of privacy data during runtime, remote attestation is a technical means to verify the legitimacy of the confidential computing environment and applications. secGear provides components that are easy to integrate and deploy, helping users quickly enable confidential computing remote attestation capabilities. + ## Acronyms and Abbreviations | Acronym/Abbreviation| Full Name | -| ------ | ----------------------------- | ---------------- | +| ------ | ----------------------------- | | REE | rich execution environment | | TEE | trusted execution environment| | EDL | enclave description language | diff --git a/docs/en/docs/secGear/secGear-installation.md b/docs/en/docs/secGear/secGear-installation.md index 277cb1631fadc6d29222ca050f03550e413efde8..34d17b1fb4881f7635a1054adb5421298dd45948 100644 --- a/docs/en/docs/secGear/secGear-installation.md +++ b/docs/en/docs/secGear/secGear-installation.md @@ -30,14 +30,14 @@ openEuler 22.03 LTS or later ### Environment Preparation - For details, see [Environment Requirements](https://www.hikunpeng.com/document/detail/en/kunpengcctrustzone/fg-tz/kunpengtrustzone_04_0006.html) and [Procedure](https://www.hikunpeng.com/document/detail/en/kunpengcctrustzone/fg-tz/kunpengtrustzone_04_0007.html) on the Kunpeng official website. +For details, see [Environment Requirements](https://www.hikunpeng.com/document/detail/en/kunpengcctrustzone/fg-tz/kunpengtrustzone_20_0018.html) and [Procedure](https://www.hikunpeng.com/document/detail/en/kunpengcctrustzone/fg-tz/kunpengtrustzone_20_0019.html) on the Kunpeng official website. ### Installation 1. Configure the openEuler Yum source. You can configure an online Yum source or configure a local Yum source by mounting an ISO file. The following uses openEuler 22.03 LTS as an example. For other versions, use the Yum source of the corresponding version. ```shell - vi openEuler.repo + /etc/yum.repo/openEuler.repo [osrepo] name=osrepo baseurl=http://repo.openeuler.org/openEuler-22.03-LTS/everything/aarch64/ @@ -103,10 +103,10 @@ Purchase a device that supports the Intel SGX feature and enable the SGX feature ```shell #Install the compiler. yum install cmake ocaml-dune - + #Install secGear. yum install secGear-devel - + #Check whether the installations are successful. If the command output is as follows, the installations are successful. rpm -qa | grep -E 'secGear|ocaml-dune|sgx' secGear-xxx diff --git "a/docs/zh/docs/A-Ops/AOps\351\203\250\347\275\262\346\214\207\345\215\227.md" "b/docs/zh/docs/A-Ops/AOps\351\203\250\347\275\262\346\214\207\345\215\227.md" index 56c9f263e3aedae8221bc46ecef9f589496061ee..5857848ccc87962391fa650c355d29a4a559a23c 100644 --- "a/docs/zh/docs/A-Ops/AOps\351\203\250\347\275\262\346\214\207\345\215\227.md" +++ "b/docs/zh/docs/A-Ops/AOps\351\203\250\347\275\262\346\214\207\345\215\227.md" @@ -2,11 +2,11 @@ ## 一、环境要求 -- 2台openEuler 23.09机器 +- 2台openEuler 24.09机器 分别用于部署check模块的两种模式：调度器，执行器。其他服务如mysql、elasticsearch、aops-manager等可在任意一台机器独立部署，为便于操作，将这些服务部署在机器A。 -- 内存尽量为8G+ +- 内存尽量为:8G+ ## 二、配置部署环境 @@ -393,7 +393,7 @@ yum install aops-check vim /etc/aops/check.ini ``` -将配置文件中各服务的地址修改为真实地址，除check服务为机器B的地址外，其他服务都部署在机器A，故需把IP地址配置为机器A的地址即可。 +将配置文件中各服务的地址修改为真实地址，除check服务为机器B的地址外，其他服务都部署在机器A，故只需把IP地址配置为机器A的地址即可。 ```shell [check] @@ -455,4 +455,4 @@ task_group_id=CHECK_TASK_GROUP_ID systemctl start aops-check ``` -至此，两台机器的服务部署完成。 \ No newline at end of file +至此，两台机器的服务部署完成。 diff --git "a/docs/zh/docs/A-Ops/aops-agent\351\203\250\347\275\262\346\214\207\345\215\227.md" "b/docs/zh/docs/A-Ops/aops-agent\351\203\250\347\275\262\346\214\207\345\215\227.md" index da0184bd611a216be79c106127936885d17e2b59..81ec4dec353887f75eacf0b7e9bf027d0e2afc9a 100644 --- "a/docs/zh/docs/A-Ops/aops-agent\351\203\250\347\275\262\346\214\207\345\215\227.md" +++ "b/docs/zh/docs/A-Ops/aops-agent\351\203\250\347\275\262\346\214\207\345\215\227.md" @@ -621,7 +621,7 @@ gala-gopher更多信息可参考文档https://gitee.com/openeuler/gala-gopher/bl } ``` -## FAQ +## 注意事项 1. 若有报错，请查看日志/var/log/aops/aops.log，根据日志中相关报错提示解决问题，并重启服务。 diff --git "a/docs/zh/docs/A-Ops/dnf\346\217\222\344\273\266\345\221\275\344\273\244\346\214\207\345\257\274\346\211\213\345\206\214.md" "b/docs/zh/docs/A-Ops/dnf\346\217\222\344\273\266\345\221\275\344\273\244\346\214\207\345\257\274\346\211\213\345\206\214.md" index a6782b7ac2ecf52c276baec8f94acc8a0fb1fbcd..01fcfba8acffcddc517f437b88a24e881c4b2f4f 100644 --- "a/docs/zh/docs/A-Ops/dnf\346\217\222\344\273\266\345\221\275\344\273\244\346\214\207\345\257\274\346\211\213\345\206\214.md" +++ "b/docs/zh/docs/A-Ops/dnf\346\217\222\344\273\266\345\221\275\344\273\244\346\214\207\345\257\274\346\211\213\345\206\214.md" @@ -227,7 +227,7 @@ command-specific options: Apply hot patch failed: redis-6.2.5-1/HP002. ``` -- Case2： 热补丁未安装时，使用`dnf hotupgrade`命令安装存在的所有热补丁，将显示安装信息。（补充：使用hotupgrade命令时，如果热补丁已安装，会提示case1中的返回信息，如果未安装，则会返回次case中的信息。） +- Case2： 热补丁未安装时，使用`dnf hotupgrade`命令安装存在的所有热补丁，将显示安装信息。（补充：使用hotupgrade命令时，如果热补丁已安装，会提示case1中的返回信息，如果未安装，则会返回本次case中的信息。） ```shell [root@openEuler A-ops]# dnf hotupgrade @@ -320,7 +320,7 @@ command-specific options: ## 使用场景说明 -本段落介绍上述命令的使用场景及顺序介绍，需要提前确认本机的热补丁repo源和相应冷补丁repo源已开启。 +本节介绍上述命令的使用场景和使用顺序，需要提前确认本机的热补丁repo源和相应冷补丁repo源已开启。 使用热补丁扫描命令查看本机待修复cve。 diff --git a/docs/zh/docs/A-Ops/figures/chuangjianyewuyu.png b/docs/zh/docs/A-Ops/figures/chuangjianyewuyu.png index 4f5b8de2d2c4ddb9bfdfba1ac17258a834561e2d..8849a2fc81dbd14328c6c66c53033164a0b67b52 100644 Binary files a/docs/zh/docs/A-Ops/figures/chuangjianyewuyu.png and b/docs/zh/docs/A-Ops/figures/chuangjianyewuyu.png differ diff --git a/docs/zh/docs/A-Ops/figures/conf_file_trace.png b/docs/zh/docs/A-Ops/figures/conf_file_trace.png new file mode 100644 index 0000000000000000000000000000000000000000..e1e518157f8def332adfa5516b37fdb89768499c Binary files /dev/null and b/docs/zh/docs/A-Ops/figures/conf_file_trace.png differ diff --git "a/docs/zh/docs/A-Ops/gala-anteater\344\275\277\347\224\250\346\211\213\345\206\214.md" "b/docs/zh/docs/A-Ops/gala-anteater\344\275\277\347\224\250\346\211\213\345\206\214.md" index cb22de01deaa10ae68de83da577831fe45337647..3ce38364e33c1ffdef169323cc0b67cad7a0019e 100644 --- "a/docs/zh/docs/A-Ops/gala-anteater\344\275\277\347\224\250\346\211\213\345\206\214.md" +++ "b/docs/zh/docs/A-Ops/gala-anteater\344\275\277\347\224\250\346\211\213\345\206\214.md" @@ -1,6 +1,6 @@ # gala-anteater使用手册 -gala-anteater是一款基于AI的操作系统异常检测平台。主要提供时序数据预处理、异常点发现、异常上报等功能。基于线下预训练、线上模型的增量学习与模型更新，能够很好地适应于多维多模态数据故障诊断。 +gala-anteater是一款基于AI的操作系统异常检测平台。主要提供时序数据预处理、异常点发现、异常上报等功能。基于线下预训练、线上模型的增量学习与模型更新，能够很好地适用于多维多模态数据故障诊断。 本文主要介绍如何部署和使用gala-anteater服务。 @@ -9,63 +9,112 @@ gala-anteater是一款基于AI的操作系统异常检测平台。主要提供 挂载repo源： ```basic -[oe-2309] # openEuler 2309 官方发布源 -name=oe2309 -baseurl=http://119.3.219.20:82/openEuler:/23.09/standard_x86_64 +[everything] +name=everything +baseurl=http://121.36.84.172/dailybuild/EBS-openEuler-24.09/EBS-openEuler-24.09/everything/$basearch/ enabled=1 gpgcheck=0 priority=1 -[oe-2309:Epol] # openEuler 2309：Epol 官方发布源 -name=oe2309_epol -baseurl=http://119.3.219.20:82/openEuler:/23.09:/Epol/standard_x86_64/ +[EPOL] +name=EPOL +baseurl=http://repo.openeuler.org/openEuler-22.03-LTS-SP4/EPOL/main/$basearch/ enabled=1 gpgcheck=0 priority=1 + ``` 安装gala-anteater： ```bash -# yum install gala-anteater +yum install gala-anteater ``` ## 配置 -> 说明：gala-anteater不包含额外需要配置的config文件，其参数通过命令行的启动参数传递。 +> 说明：gala-anteater采用配置的config文件设置参数启动，配置文件位置: /etc/gala-anteater/config/gala-anteater.yaml。 -##### 启动参数介绍 +##### 配置文件默认参数 -| 参数项 | 参数详细名 | 类型 | 是否必须 | 默认值 | 名称 | 含义 | -|---|---|---|---|---|---|---| -| -ks | --kafka_server | string | True | | KAFKA_SERVER | Kafka Server的ip地址，如：localhost / xxx.xxx.xxx.xxx | -| -kp | --kafka_port | string | True | | KAFKA_PORT | Kafka Server的port，如：9092 | -| -ps | --prometheus_server | string | True | | PROMETHEUS_SERVER | Prometheus Server的ip地址，如：localhost / xxx.xxx.xxx.xxx | -| -pp | --prometheus_port | string | True | | PROMETHEUS_PORT | Prometheus Server的port，如：9090 | -| -m | --model | string | False | vae | MODEL | 异常检测模型，目前支持两种异常检测模型，可选（random_forest，vae）
random_forest：随机森林模型，不支持在线学习
vae：Variational Atuoencoder，无监督模型，支持首次启动时，利用历史数据，进行模型更新迭代 | -| -d | --duration | int | False | 1 | DURATION | 异常检测模型执行频率（单位：分），每x分钟，检测一次 | -| -r | --retrain | bool | False | False | RETRAIN | 是否在启动时，利用历史数据，进行模型更新迭代，目前仅支持vae模型 | -| -l | --look_back | int | False | 4 | LOOK_BACK | 利用过去x天的历史数据，更新模型 | -| -t | --threshold | float | False | 0.8 | THRESHOLD | 异常检测模型的阈值：（0,1），较大的值，能够减少模型的误报率，推荐大于等于0.5 | -| -sli | --sli_time | int | False | 400 | SLI_TIME | 表示应用性能指标（单位：毫秒），较大的值，能够减少模型的误报率，推荐大于等于200
对于误报率较高的场景，推荐1000以上 | +```yaml +Global: + data_source: "prometheus" -## 启动 +Arangodb: + url: "http://localhost:8529" + db_name: "spider" -执行如下命令启动gala-anteater。 +Kafka:f + server: "192.168.122.100" + port: "9092" + model_topic: "gala_anteater_hybrid_model" + rca_topic: "gala_cause_inference" + meta_topic: "gala_gopher_metadata" + group_id: "gala_anteater_kafka" + # auth_type: plaintext/sasl_plaintext, please set "" for no auth + auth_type: "" + username: "" + password: "" -> 说明：gala-anteter支持命令行方式启动运行，不支持systemd方式。 +Prometheus: + server: "localhost" + port: "9090" + steps: "5" -### 在线训练方式运行（推荐） +Aom: + base_url: "" + project_id: "" + auth_type: "token" + auth_info: + iam_server: "" + iam_domain: "" + iam_user_name: "" + iam_password: "" + ssl_verify: 0 + +Schedule: + duration: 1 -```bash -gala-anteater -ks {ip} -kp {port} -ps {ip} -pp {port} -m vae -r True -l 7 -t 0.6 -sli 400 ``` -### 普通方式运行 +| 参数 | 含义 | 默认值 | +| ----------- | --------------------------------------------------- | ---------------------------- | +| Global | | | +| data_source | 设置数据来源 | “prometheus” | +| Arangodb | | | +| url | 图数据库Arangodb的ip地址 | "http://localhost:8529" | +| db_name | 图数据库名 | "spider" | +| Kafka | | | +| server | Kafka Server的ip地址，根据安装节点ip配置 | | +| port | Kafka Server的port，如：9092 | | +| model_topic | 故障检测结果上报topic | "gala_anteater_hybrid_model" | +| rca_topic | 根因定位结果上报topic | "gala_cause_inference" | +| meta_topic | gopher采集指标数据topic | "gala_gopher_metadata" | +| group_id | kafka设置组名 | "gala_anteater_kafka" | +| Prometheus | | | +| server | Prometheus Server的ip地址，根据安装节点ip配置 | | +| port | Prometheus Server的port，如：9090 | | +| steps | 指标采样间隔 | | +| Schedule | | | +| duration | 异常检测模型执行频率（单位：分），每x分钟，检测一次 | 1 | -```bash -gala-anteater -ks {ip} -kp {port} -ps {ip} -pp {port} -m vae -t 0.6 -sli 400 +## 启动 + +执行如下命令启动gala-anteater +``` +systemctl start gala-anteater ``` +** 注意 **：gala-anteater支持启动一个进程实例，启动多个会导致内存占用过大，日志混乱。 +### 故障注入 +gala-anteater为故障检测与根因定位模块，测试阶段需要通过故障注入来构造故障，从而通过故障检测和根因定位模块获得故障节点信息和故障传播根因节点信息。 +* 故障注入（仅提供参考） + ```bash + chaosblade create disk burn --size 10 --read --write --path /var/lib/docker/overlay2/cf0a469be8a84cabe1d057216505f8d64735e9c63159e170743353a208f6c268/merged --timeout 120 + + ``` + *chaosblade 为故障注入工具， 可以模拟各种故障， 包括但不限于磁盘故障、网络故障、IO故障等待 + 备注： 通过注入不一样的故障， 指标采集器(例如 gala-gopher) 监控关联指标并上报到 promethues 模块， prometheus graph 指标图部分关联指标会存在明显波动。 ### 查询gala-anteater服务状态 @@ -101,9 +150,9 @@ gala-anteater -ks {ip} -kp {port} -ps {ip} -pp {port} -m vae -t 0.6 -sli 400 2022-09-01 17:53:57,975 - apscheduler.scheduler - DEBUG - Next wakeup is due at 2022-09-01 17:54:57.973533+08:00 (in 59.998006 seconds) ``` -## 输出数据 +## 异常检测输出数据 -gala-anteater如果检测到的异常点，会将结果输出至kafka。输出数据格式如下： +gala-anteater如果检测到异常点，会将结果输出至kafka的model_topic，输出数据格式如下： ```json { @@ -151,3 +200,190 @@ gala-anteater如果检测到的异常点，会将结果输出至kafka。输出 "Body":"TimeStamp, WARN, APP may be impacting sli performance issues." } ``` + +## 根因定位输出数据 + +异常检测结果的每个异常节点都会触发根因定位，根因定位的结果会上报至kafka的rca_topic。输出数据格式如下： + +```yaml +{ + "Timestamp": 1724287883452, + "event_id": "1721125159975_475ae627-7e88-41ed-8bb8-ff0fee95a69d_l7_3459438_192.168.11.103_192.168.11.102_26_tcp_server_server_http", + "Attributes": { + "event_id": "1721125159975_475ae627-7e88-41ed-8bb8-ff0fee95a69d_l7_3459438_192.168.11.103_192.168.11.102_26_tcp_server_server_http", + "event_source": "root-cause-inference" + }, + "Resource": { + "abnormal_kpi": { + "metric_id": "gala_gopher_l7_latency_sum", + "entity_id": "", + "metric_labels": { + "client_ip": "192.168.11.103", + "comm": "python", + "container_id": "83d0c2f4a7f4", + "container_image": "ba2d060a624e", + "container_name": "/k8s_backend_backend-node2-01-5bcb47fd7c-4jxxs_default_475ae627", + "instance": "192.168.122.102:8888", + "job": "192.168.122.102", + "l4_role": "tcp_server", + "l7_role": "server", + "machine_id": "66086618-3bad-489e-b17d-05245224f29a-192.168.122.102", + "pod": "default/backend-node2-01-5bcb47fd7c-4jxxs", + "pod_id": "475ae627-7e88-41ed-8bb8-ff0fee95a69d", + "pod_namespace": "default", + "protocol": "http", + "server_ip": "192.168.11.102", + "server_port": "26", + "ssl": "no_ssl", + "tgid": "3459438" + }, + "desc": "L7 session averaged latency.", + "score": 0.3498585816683402 + }, + "cause_metrics": [ + { + "metric_id": "gala_gopher_container_cpu_user_seconds_total@4a9fcc23-8ba2-4b0a-bcb0-b1bfd89ed929", + "entity_id": "", + "metric_labels": { + "container_id": "1319ff912a6f", + "container_image": "ba2d060a624e", + "container_name": "/k8s_backend_backend-node3-02-654dd97bf9-s8jg5_default_4a9fcc23", + "instance": "192.168.122.103:8888", + "job": "192.168.122.103", + "machine_id": "494a61be-23cc-4c97-a871-902866e43747-192.168.122.103", + "pod": "default/backend-node3-02-654dd97bf9-s8jg5", + "pod_id": "4a9fcc23-8ba2-4b0a-bcb0-b1bfd89ed929", + "pod_namespace": "default" + }, + "desc": "\u5bb9\u56681s\u5185\u7528\u6237\u6001CPU\u8d1f\u8f7d", + "keyword": "process", + "score": 0.1194249668036936, + "path": [ + { + "pod_id": "4a9fcc23-8ba2-4b0a-bcb0-b1bfd89ed929", + "pod": "default/backend-node3-02-654dd97bf9-s8jg5", + "instance": "192.168.122.103:8888", + "job": "192.168.122.103", + "pod_state": "normal" + }, + { + "pod_id": "475ae627-7e88-41ed-8bb8-ff0fee95a69d", + "pod": "default/backend-node2-01-5bcb47fd7c-4jxxs", + "instance": "192.168.122.102:8888", + "job": "192.168.122.102", + "pod_state": "abnormal" + } + ] + }, + { + "metric_id": "gala_gopher_proc_wchar_bytes@67134fb4-b2a3-43c5-a5b3-b3b463ad7d43", + "entity_id": "", + "metric_labels": { + "cmdline": "python ./backend.py ", + "comm": "python", + "container_id": "de570c7328bb", + "container_image": "ba2d060a624e", + "container_name": "/k8s_backend_backend-node2-02-548c79d989-bnl9g_default_67134fb4", + "instance": "192.168.122.102:8888", + "job": "192.168.122.102", + "machine_id": "66086618-3bad-489e-b17d-05245224f29a-192.168.122.102", + "pgid": "3459969", + "pod": "default/backend-node2-02-548c79d989-bnl9g", + "pod_id": "67134fb4-b2a3-43c5-a5b3-b3b463ad7d43", + "pod_namespace": "default", + "ppid": "3459936", + "start_time": "1139543501", + "tgid": "3459969" + }, + "desc": "\u8fdb\u7a0b\u7cfb\u7edf\u8c03\u7528\u81f3FS\u7684\u5199\u5b57\u8282\u6570", + "keyword": "process", + "score": 0.37121879175399997, + "path": [ + { + "pod_id": "67134fb4-b2a3-43c5-a5b3-b3b463ad7d43", + "pod": "default/backend-node2-02-548c79d989-bnl9g", + "instance": "192.168.122.102:8888", + "job": "192.168.122.102", + "pod_state": "normal" + }, + { + "pod_id": "4a9fcc23-8ba2-4b0a-bcb0-b1bfd89ed929", + "pod": "default/backend-node3-02-654dd97bf9-s8jg5", + "instance": "192.168.122.103:8888", + "job": "192.168.122.103", + "pod_state": "normal" + }, + { + "pod_id": "475ae627-7e88-41ed-8bb8-ff0fee95a69d", + "pod": "default/backend-node2-01-5bcb47fd7c-4jxxs", + "instance": "192.168.122.102:8888", + "job": "192.168.122.102", + "pod_state": "abnormal" + } + ] + }, + { + "metric_id": "gala_gopher_l7_latency_avg@956c70a2-9918-459c-a0a8-39396251f952", + "entity_id": "", + "metric_labels": { + "client_ip": "192.168.11.103", + "comm": "python", + "container_id": "eef1ca1082a7", + "container_image": "ba2d060a624e", + "container_name": "/k8s_backend_backend-node2-03-584f4c6cfd-w4d2b_default_956c70a2", + "instance": "192.168.122.102:8888", + "job": "192.168.122.102", + "l4_role": "tcp_server", + "l7_role": "server", + "machine_id": "66086618-3bad-489e-b17d-05245224f29a-192.168.122.102", + "pod": "default/backend-node2-03-584f4c6cfd-w4d2b", + "pod_id": "956c70a2-9918-459c-a0a8-39396251f952", + "pod_namespace": "default", + "protocol": "http", + "server_ip": "192.168.11.113", + "server_port": "26", + "ssl": "no_ssl", + "tgid": "3460169" + }, + "desc": "L7 session averaged latency.", + "keyword": null, + "score": 0.5624857367147617, + "path": [ + { + "pod_id": "956c70a2-9918-459c-a0a8-39396251f952", + "pod": "default/backend-node2-03-584f4c6cfd-w4d2b", + "instance": "192.168.122.102:8888", + "job": "192.168.122.102", + "pod_state": "abnormal" + }, + { + "pod_id": "4a9fcc23-8ba2-4b0a-bcb0-b1bfd89ed929", + "pod": "default/backend-node3-02-654dd97bf9-s8jg5", + "instance": "192.168.122.103:8888", + "job": "192.168.122.103", + "pod_state": "normal" + }, + { + "pod_id": "475ae627-7e88-41ed-8bb8-ff0fee95a69d", + "pod": "default/backend-node2-01-5bcb47fd7c-4jxxs", + "instance": "192.168.122.102:8888", + "job": "192.168.122.102", + "pod_state": "abnormal" + } + ] + } + ] + }, + "desc": "L7 session averaged latency.", + "top1": "gala_gopher_container_cpu_user_seconds_total@4a9fcc23-8ba2-4b0a-bcb0-b1bfd89ed929\u5f02\u5e38", + "top2": "gala_gopher_proc_wchar_bytes@67134fb4-b2a3-43c5-a5b3-b3b463ad7d43\u5f02\u5e38", + "top3": "gala_gopher_l7_latency_avg@956c70a2-9918-459c-a0a8-39396251f952\u5f02\u5e38", + "keywords": [ + "process", + null + ], + "SeverityText": "WARN", + "SeverityNumber": 13, + "Body": "A cause inferring event for an abnormal event" +} +``` \ No newline at end of file diff --git "a/docs/zh/docs/A-Ops/gala-gopher\344\275\277\347\224\250\346\211\213\345\206\214.md" "b/docs/zh/docs/A-Ops/gala-gopher\344\275\277\347\224\250\346\211\213\345\206\214.md" index df94faa69bae053c932b0ae757d9a114d5a1c7ac..571247a8b5e055c944220a812eaabc044e824527 100644 --- "a/docs/zh/docs/A-Ops/gala-gopher\344\275\277\347\224\250\346\211\213\345\206\214.md" +++ "b/docs/zh/docs/A-Ops/gala-gopher\344\275\277\347\224\250\346\211\213\345\206\214.md" @@ -1042,6 +1042,84 @@ file_conn_head：记录java进程的最后一个sessionId，以备L7probe读jsse 将sock_conn和conn_data上报到map中。 +## sliprobe 介绍 + +基于 ebpf 采集并周期性上报容器粒度的 SLI 指标。 + +### 特性 + +- 按照容器粒度采集周期内CPU调度事件的时延总计和统计直方图，关注的事件包括：调度等待，主动睡眠，锁/IO引起的阻塞，调度延迟，长系统调用等 +- 按照容器粒度采集周期内Memory分配事件的时延总计和统计直方图，关注的事件包括：内存回收，换页，内存规整等 +- 按照容器粒度采集周期内BIO层IO操作的时延总计和统计直方图 + +### 使用说明 + +启动命令示例：指定上报周期为15秒，观测容器id为abcd12345678和abcd87654321的两个容器的SLI指标。 + +```shell +curl -X PUT http://localhost:9999/sli -d json='{"params":{"report_period":15}, "snoopers":{"container_id":[{"container_id": "abcd12345678","abcd87654321"}]}, "state":"running"}' +``` + +### 代码逻辑 +#### 总体思路 + +1. 用户态接收待观测的容器列表，将容器的cpuacct子系统目录inode记录在ebpf map中，共享给内核态。 + +2. 通过ebpf kprobe/tracepoint跟踪相关内核事件，判断当前进程是否属于待观测范围，记录事件类型，时间戳等信息。每隔一定周期将同一cgroup内进程的SLI指标进行聚合上报。 +3. 用户态接收并打印内核态上报的SLI指标信息。 + +#### SLI指标计算方式 + +##### CPU SLI + +1. **cpu_wait** + + 在sched_stat_wait观测点，获取第二个参数delay的值 + +2. **cpu_sleep** + + 在sched_stat_sleep观测点，获取第二个参数delay的值 + +3. **cpu_iowait** + + 在sched_stat_blocked观测点，判断当前进程in_iowait，则获取第二个参数delay的值 + +4. **cpu_block** + + 在sched_stat_blocked观测点，判断当前进程非in_iowait，则获取第二个参数delay的值 + +5. **cpu_rundelay** + + 在sched_switch观测点，通过第三个参数next获取将被调度进程的run_delay值：next->sched_info.run_delay，记录在task_sched_map中。计算同一进程两次被调度时run_delay的差值 + +6. **cpu_longsys** + + 在sched_switch观测点，通过第三个参数next获取将被调度进程的task结构体，从task结构体中获取上下文切换次数（nvcsw+nivcsw）和用户态执行时间utime。如果同一进程两次被调度时的上下文切换次数和用户态执行时间都不变，则说明在该进程在执行一个较长的系统调用，累积该进程处在内核态的时间 + +##### MEM SLI + +1. **mem_reclaim** + + 计算mem_cgroup_handle_over_high函数返回时间戳和进入时间戳的差值 + + 计算mm_vmscan_memcg_reclaim_end观测点和mm_vmscan_memcg_reclaim_begin观测点时间戳的差值 + +2. **mem_swapin** + + 计算do_swap_page函数返回时间戳和进入时间戳的差值 + +3. **mem_compact** + + 计算try_to_compact_pages函数返回时间戳和进入时间戳的差值 + +##### IO SLI + +1. **bio_latency** + + 计算进入bio_endio函数和触发block_bio_queue观测点的时间戳差值 + + 计算进入bio_endio函数和退出generic_make_request_checks函数的时间戳差值 + ## 使用方法 @@ -1049,15 +1127,15 @@ file_conn_head：记录java进程的最后一个sessionId，以备L7probe读jsse  -如上图所示，绿色部分为gala-gopher的外部依赖组件。gala-gopher会将指标数据metrics输出到promethous，将元数据metadata、异常事件event输出到kafka，灰色部分的gala-anteater和gala-spider会从promethous和kafka获取数据。 +如上图所示，绿色部分为gala-gopher的外部依赖组件。gala-gopher会将指标数据metrics输出到prometheus，将元数据metadata、异常事件event输出到kafka，灰色部分的gala-anteater和gala-spider会从prometheus和kafka获取数据。 -> 说明：安装kafka、promethous软件包时，需要从官网获取安装包进行部署。 +> 说明：安装kafka、prometheus软件包时，需要从官网获取安装包进行部署。 ### 输出数据 - **指标数据metrics** - Promethous Server内置了Express Browser UI，用户可以通过PromQL查询语句查询指标数据内容。详细教程参见官方文档：[Using the expression browser](https://prometheus.io/docs/prometheus/latest/getting_started/#using-the-expression-browser)。示例如下： + Prometheus Server内置了Express Browser UI，用户可以通过PromQL查询语句查询指标数据内容。详细教程参见官方文档：[Using the expression browser](https://prometheus.io/docs/prometheus/latest/getting_started/#using-the-expression-browser)。示例如下： 指定指标名称为`gala_gopher_tcp_link_rcv_rtt`，UI显示的指标数据为： diff --git "a/docs/zh/docs/A-Ops/image/\344\273\273\345\212\241\347\273\223\346\236\234\346\237\245\347\234\213.png" "b/docs/zh/docs/A-Ops/image/\344\273\273\345\212\241\347\273\223\346\236\234\346\237\245\347\234\213.png" new file mode 100644 index 0000000000000000000000000000000000000000..31fe24f44facaaa62fbeddd3eef0090a3be88908 Binary files /dev/null and "b/docs/zh/docs/A-Ops/image/\344\273\273\345\212\241\347\273\223\346\236\234\346\237\245\347\234\213.png" differ diff --git "a/docs/zh/docs/A-Ops/image/\345\210\233\345\273\272\350\204\232\346\234\254.png" "b/docs/zh/docs/A-Ops/image/\345\210\233\345\273\272\350\204\232\346\234\254.png" new file mode 100644 index 0000000000000000000000000000000000000000..feb95836d056335d9d7ef673acc5fdf39e29bd8e Binary files /dev/null and "b/docs/zh/docs/A-Ops/image/\345\210\233\345\273\272\350\204\232\346\234\254.png" differ diff --git "a/docs/zh/docs/A-Ops/image/\345\210\233\345\273\272\350\204\232\346\234\254\344\273\273\345\212\241.png" "b/docs/zh/docs/A-Ops/image/\345\210\233\345\273\272\350\204\232\346\234\254\344\273\273\345\212\241.png" new file mode 100644 index 0000000000000000000000000000000000000000..e7b1c5fc77c4027f1cdb96941440220db8637e5f Binary files /dev/null and "b/docs/zh/docs/A-Ops/image/\345\210\233\345\273\272\350\204\232\346\234\254\344\273\273\345\212\241.png" differ diff --git "a/docs/zh/docs/A-Ops/image/\345\215\225\346\254\241\346\211\247\350\241\214.png" "b/docs/zh/docs/A-Ops/image/\345\215\225\346\254\241\346\211\247\350\241\214.png" new file mode 100644 index 0000000000000000000000000000000000000000..8020c60843c11e566778a1a03c1fa7516de9dd6b Binary files /dev/null and "b/docs/zh/docs/A-Ops/image/\345\215\225\346\254\241\346\211\247\350\241\214.png" differ diff --git "a/docs/zh/docs/A-Ops/image/\345\221\250\346\234\237\346\211\247\350\241\214.png" "b/docs/zh/docs/A-Ops/image/\345\221\250\346\234\237\346\211\247\350\241\214.png" new file mode 100644 index 0000000000000000000000000000000000000000..b75743556384fe58690847b3794607ef9a890d6d Binary files /dev/null and "b/docs/zh/docs/A-Ops/image/\345\221\250\346\234\237\346\211\247\350\241\214.png" differ diff --git "a/docs/zh/docs/A-Ops/image/\345\221\275\344\273\244\346\211\247\350\241\214.png" "b/docs/zh/docs/A-Ops/image/\345\221\275\344\273\244\346\211\247\350\241\214.png" new file mode 100644 index 0000000000000000000000000000000000000000..b5c9fbbeb5a4bba5f81d753fa5aa620ad261804c Binary files /dev/null and "b/docs/zh/docs/A-Ops/image/\345\221\275\344\273\244\346\211\247\350\241\214.png" differ diff --git "a/docs/zh/docs/A-Ops/image/\345\221\275\344\273\244\347\256\241\347\220\206\347\225\214\351\235\242.png" "b/docs/zh/docs/A-Ops/image/\345\221\275\344\273\244\347\256\241\347\220\206\347\225\214\351\235\242.png" new file mode 100644 index 0000000000000000000000000000000000000000..c0357fc88d33c8b706203b70016d53629a3db70c Binary files /dev/null and "b/docs/zh/docs/A-Ops/image/\345\221\275\344\273\244\347\256\241\347\220\206\347\225\214\351\235\242.png" differ diff --git "a/docs/zh/docs/A-Ops/image/\346\223\215\344\275\234\347\256\241\347\220\206.png" "b/docs/zh/docs/A-Ops/image/\346\223\215\344\275\234\347\256\241\347\220\206.png" new file mode 100644 index 0000000000000000000000000000000000000000..3a1b8c3accdfb688da2e8e54eb17e86d18ee4d0b Binary files /dev/null and "b/docs/zh/docs/A-Ops/image/\346\223\215\344\275\234\347\256\241\347\220\206.png" differ diff --git "a/docs/zh/docs/A-Ops/image/\346\226\207\344\273\266\346\216\250\351\200\201.png" "b/docs/zh/docs/A-Ops/image/\346\226\207\344\273\266\346\216\250\351\200\201.png" new file mode 100644 index 0000000000000000000000000000000000000000..c449eb18608e0146275f1b9f4ca41d05d48af021 Binary files /dev/null and "b/docs/zh/docs/A-Ops/image/\346\226\207\344\273\266\346\216\250\351\200\201.png" differ diff --git "a/docs/zh/docs/A-Ops/image/\346\226\260\345\273\272\345\221\275\344\273\244.png" "b/docs/zh/docs/A-Ops/image/\346\226\260\345\273\272\345\221\275\344\273\244.png" new file mode 100644 index 0000000000000000000000000000000000000000..50d5bd4ce5499512acf2b8af86445fe6df6ce29f Binary files /dev/null and "b/docs/zh/docs/A-Ops/image/\346\226\260\345\273\272\345\221\275\344\273\244.png" differ diff --git "a/docs/zh/docs/A-Ops/image/\346\226\260\345\273\272\345\221\275\344\273\244\344\273\273\345\212\241.png" "b/docs/zh/docs/A-Ops/image/\346\226\260\345\273\272\345\221\275\344\273\244\344\273\273\345\212\241.png" new file mode 100644 index 0000000000000000000000000000000000000000..792ec4e81017575fd27466a275c0502563808296 Binary files /dev/null and "b/docs/zh/docs/A-Ops/image/\346\226\260\345\273\272\345\221\275\344\273\244\344\273\273\345\212\241.png" differ diff --git "a/docs/zh/docs/A-Ops/image/\350\204\232\346\234\254\346\211\247\350\241\214.png" "b/docs/zh/docs/A-Ops/image/\350\204\232\346\234\254\346\211\247\350\241\214.png" new file mode 100644 index 0000000000000000000000000000000000000000..4ab626ad5949e17a5d486431ae4c0481ca42a442 Binary files /dev/null and "b/docs/zh/docs/A-Ops/image/\350\204\232\346\234\254\346\211\247\350\241\214.png" differ diff --git "a/docs/zh/docs/A-Ops/image/\350\204\232\346\234\254\347\256\241\347\220\206.png" "b/docs/zh/docs/A-Ops/image/\350\204\232\346\234\254\347\256\241\347\220\206.png" new file mode 100644 index 0000000000000000000000000000000000000000..62c60399dc58a79a9ab48a7eb584ce615c11b05c Binary files /dev/null and "b/docs/zh/docs/A-Ops/image/\350\204\232\346\234\254\347\256\241\347\220\206.png" differ diff --git "a/docs/zh/docs/A-Ops/\347\244\276\345\214\272\347\203\255\350\241\245\344\270\201\345\210\266\344\275\234\345\217\221\345\270\203\346\265\201\347\250\213.md" "b/docs/zh/docs/A-Ops/\347\244\276\345\214\272\347\203\255\350\241\245\344\270\201\345\210\266\344\275\234\345\217\221\345\270\203\346\265\201\347\250\213.md" index 1c2d4ab7fabed91e8dce2ed214ec26afd1dea637..badbd49f038a3ba7920b61cb5d3479ed773027b1 100644 --- "a/docs/zh/docs/A-Ops/\347\244\276\345\214\272\347\203\255\350\241\245\344\270\201\345\210\266\344\275\234\345\217\221\345\270\203\346\265\201\347\250\213.md" +++ "b/docs/zh/docs/A-Ops/\347\244\276\345\214\272\347\203\255\350\241\245\344\270\201\345\210\266\344\275\234\345\217\221\345\270\203\346\265\201\347\250\213.md" @@ -200,7 +200,7 @@ pr内容： ### 2、生成安全公告热补丁信息 -社区根据收集到的热补丁issue信息，在生成安全公告的同时生成hotpatch字段补丁，过滤已经发布的漏洞。 +社区根据收集到的热补丁issue信息，在生成安全公告的同时生成hotpatch字段补丁，过滤已经发布的漏洞补丁。 - 在安全公告文件新增HotPatchTree字段，记录和公告相关漏洞的热补丁，每个补丁按架构和CVE字段区分（Type=ProductName 记录分支，Type=ProductArch 记录补丁具体的rpm包）。 diff --git "a/docs/zh/docs/A-Ops/\350\207\252\345\212\250\345\214\226\350\277\220\347\273\264\346\234\215\345\212\241\344\275\277\347\224\250\346\211\213\345\206\214.md" "b/docs/zh/docs/A-Ops/\350\207\252\345\212\250\345\214\226\350\277\220\347\273\264\346\234\215\345\212\241\344\275\277\347\224\250\346\211\213\345\206\214.md" new file mode 100644 index 0000000000000000000000000000000000000000..c075767137aa34c9753000d5752f1789fa97f88f --- /dev/null +++ "b/docs/zh/docs/A-Ops/\350\207\252\345\212\250\345\214\226\350\277\220\347\273\264\346\234\215\345\212\241\344\275\277\347\224\250\346\211\213\345\206\214.md" @@ -0,0 +1,66 @@ +# 自动化运维服务使用手册 + +## 主要功能 + +本服务主要包括批量命令执行和批量脚本执行的功能，两者均支持定时任务。 + +#### 命令相关 + +命令页面包含命令管理和命令执行两个页签 + +##### 命令管理 + +命令管理界面可以对命令进行增删查改功能： + + + + +##### 命令执行 + +命令执行界面可以创建命令执行任务： + + + +命令执行界面可以对创建的任务进行任务信息查看，任务执行，任务结果查看，删除任务等操作： + +任务结果查看： + + + +#### 脚本相关 + +脚本页面包含脚本管理、脚本执行、操作管理三个页签 + +##### 操作管理 + +为了屏蔽操作系统的架构，系统对脚本执行的影响，抽象出操作的概念。一个操作对应一组包括各类架构和系统的脚本，脚本执行时选择主机和操作后，根据主机的系统和架构选择对应的脚本进行执行。 + +操作管理界面可以对操作进行增删查改功能： + + + +##### 脚本管理 + +脚本管理界面可以对脚本进行上传，查询，删除，编辑功能： + +创建脚本： + + +##### 脚本执行 + +脚本执行界面可以创建脚本执行任务，创建脚本任务仅能通过选择操作来选择对应脚本： + +创建脚本任务： + + +#### 定时任务 + +定时任务支持指定时间执行和周期执行功能 +单次执行： + +周期执行： + +#### 文件推送 + +文件推送功能支持将脚本推送至指定目录，此类任务不会执行脚本，且推送任务与定时任务互斥： + \ No newline at end of file diff --git "a/docs/zh/docs/A-Ops/\351\205\215\347\275\256\346\272\257\346\272\220\346\234\215\345\212\241\344\275\277\347\224\250\346\211\213\345\206\214.md" "b/docs/zh/docs/A-Ops/\351\205\215\347\275\256\346\272\257\346\272\220\346\234\215\345\212\241\344\275\277\347\224\250\346\211\213\345\206\214.md" index 2d65810c8165b028cea96792b1db600a84c2dd9e..d694fc7092316ce414f95d314295e8a831acdf6d 100644 --- "a/docs/zh/docs/A-Ops/\351\205\215\347\275\256\346\272\257\346\272\220\346\234\215\345\212\241\344\275\277\347\224\250\346\211\213\345\206\214.md" +++ "b/docs/zh/docs/A-Ops/\351\205\215\347\275\256\346\272\257\346\272\220\346\234\215\345\212\241\344\275\277\347\224\250\346\211\213\345\206\214.md" @@ -149,3 +149,11 @@ port = 11114 #### 配置同步  + +#### 配置文件追溯 +##### 打开监控开关 + +##### 配置文件修改记录追溯 + + + diff --git a/docs/zh/docs/A-Tune/native-turbo.md b/docs/zh/docs/A-Tune/native-turbo.md index 93817638470e1a8548de2292190ae12d52e761e4..af52f6d94e2863ae47389ebfd43a3d4f6f6bf4ad 100644 --- a/docs/zh/docs/A-Tune/native-turbo.md +++ b/docs/zh/docs/A-Tune/native-turbo.md @@ -46,10 +46,9 @@ 2. 使用前需要预留足够的大页，否则程序会执行失败。 如果使用cgroup，请注意hugetlb的限制，如果限制小于所需大页数量，可能导致运行时崩溃。 - + 3. 由于进程页表改为2M，mprotect等系统调用的参数需要按2M对齐，否则会执行失败。 4. 不支持libcareplus热补丁机制。 5. 多个进程间无法共享大页，会消耗多倍内存。 - diff --git "a/docs/zh/docs/A-Tune/\345\270\270\350\247\201\351\227\256\351\242\230\344\270\216\350\247\243\345\206\263\346\226\271\346\263\225.md" "b/docs/zh/docs/A-Tune/\345\270\270\350\247\201\351\227\256\351\242\230\344\270\216\350\247\243\345\206\263\346\226\271\346\263\225.md" deleted file mode 100644 index 52bed705a43e1dc733bf3beb167a9c93d18c35d2..0000000000000000000000000000000000000000 --- "a/docs/zh/docs/A-Tune/\345\270\270\350\247\201\351\227\256\351\242\230\344\270\216\350\247\243\345\206\263\346\226\271\346\263\225.md" +++ /dev/null @@ -1,52 +0,0 @@ -# 常见问题与解决方法 - -## **问题1：train命令训练模型出错，提示“training data failed”** - -原因：collection命令只采集一种类型的数据。 - -解决方法：至少采集两种数据类型的数据进行训练。 - -## **问题2：atune-adm无法连接atuned服务** - -可能原因： - -1. 检查atuned服务是否启动，并检查atuned侦听地址。 - - ```shell - # systemctl status atuned - # netstat -nap | grep atuned - ``` - -2. 防火墙阻止了atuned的侦听端口。 -3. 系统配置了http代理导致无法连接。 - -解决方法： - -1. 如果atuned没有启动，启动该服务，参考命令如下： - - ```shell - # systemctl start atuned - ``` - -2. 分别在atuned和atune-adm的服务器上执行如下命令，允许侦听端口接收网络包，其中60001为atuned的侦听端口号。 - - ```shell - # iptables -I INPUT -p tcp --dport 60001 -j ACCEPT - # iptables -I INPUT -p tcp --sport 60001 -j ACCEPT - ``` - -3. 不影响业务的前提下删除http代理，或对侦听IP不进行http代理，命令如下： - - ```shell - # no_proxy=$no_proxy,侦听地址 - ``` - -## **问题3：atuned服务无法启动，提示“Job for atuned.service failed because a timeout was exceeded.”** - -原因：hosts文件中缺少localhost配置 - -解决方法：在/etc/hosts文件中127.0.0.1这一行添加上localhost - -```conf -127.0.0.1 localhost localhost.localdomain localhost4 localhost4.localdomain4 -``` diff --git "a/docs/zh/docs/AI/AI\345\244\247\346\250\241\345\236\213\346\234\215\345\212\241\351\225\234\345\203\217\344\275\277\347\224\250\346\214\207\345\215\227.md" "b/docs/zh/docs/AI/AI\345\244\247\346\250\241\345\236\213\346\234\215\345\212\241\351\225\234\345\203\217\344\275\277\347\224\250\346\214\207\345\215\227.md" new file mode 100644 index 0000000000000000000000000000000000000000..c7c492b104b74e25ac87980c2d8580885a43df0e --- /dev/null +++ "b/docs/zh/docs/AI/AI\345\244\247\346\250\241\345\236\213\346\234\215\345\212\241\351\225\234\345\203\217\344\275\277\347\224\250\346\214\207\345\215\227.md" @@ -0,0 +1,94 @@ +# 支持百川、chatglm、星火等AI大模型的容器化封装 + +已配好相关依赖，分为CPU和GPU版本，降低使用门槛，开箱即用。 + +## 拉取镜像(CPU版本) + +```bash +docker pull openeuler/llm-server:1.0.0-oe2203sp3 +``` + +## 拉取镜像(GPU版本) + +```bash +docker pull icewangds/llm-server:1.0.0 +``` + +## 下载模型, 并转换为gguf格式 + +```bash +# 安装huggingface +pip install huggingface-hub + +# 下载你想要部署的模型 +export HF_ENDPOINT=https://hf-mirror.com +huggingface-cli download --resume-download baichuan-inc/Baichuan2-13B-Chat --local-dir /root/models/Baichuan2-13B-Chat --local-dir-use-symlinks False + +# gguf格式转换 +cd /root/models/ +git clone https://github.com/ggerganov/llama.cpp.git +python llama.cpp/convert-hf-to-gguf.py ./Baichuan2-13B-Chat +# 生成的gguf格式的模型路径 /root/models/Baichuan2-13B-Chat/ggml-model-f16.gguf +``` + +## 启动方式 + +需要Docker v25.0.0及以上版本。 + +若使用GPU镜像，需要OS上安装nvidia-container-toolkit，安装方式见
| 参数名称 | +取值 | +功能 | +
|---|---|---|
| ima_appraise | +enforce-evm | +IMA评估强制校验模式（EVM开启） | +
| log-evm | +IMA评估日志模式（EVM开启） | +|
| enforce | +IMA评估强制校验模式 | +|
| log | +IMA评估日志模式 | +|
| off | +关闭IMA评估 | +|
| ima_appraise_digest_list | +digest | +基于摘要列表进行IMA+EVM评估（比较文件内容和扩展属性） | +
| digest-nometadata | +基于摘要列表进行IMA评估（只比较文件内容） | +|
| evm | +x509 | +直接开启基于可移植签名的EVM（无论EVM证书是否加载） | +
| complete | +启动后不允许通过securityfs接口修改EVM模式 | +|
| allow_metadata_writes | +允许修改文件元数据，EVM不做拦截 | +|
| ima_hash | +sha256/sha1/... | +声明IMA度量哈希算法 | +
| ima_template | +ima | +声明IMA度量模板（d|n） | +
| ima-ng | +声明IMA度量模板（d-ng|n-ng），默认使用该模板 | +|
| ima-sig | +声明IMA度量模板（d-ng|n-ng|sig） | +|
| ima_policy | +exec_tcb | +度量所有执行、映射方式访问的文件，以及加载的内核模块、固件、内核等文件 | +
| tcb | +在exec_tcb策略的基础上，额外度量以uid=0或euid=0身份访问的文件 | +|
| secure_boot | +评估所有加载的内核模块、固件、内核等文件，并指定使用IMA签名模式 | +|
| appraise_exec_tcb | +在secure_boot策略的基础上，额外评估所有执行、映射方式访问的文件 | +|
| appraise_tcb | +评估访问的所有属主为0的文件 | +|
| appraise_exec_immutable | +与appraise_exec_tcb策略配合使用，可执行文件的扩展属性不可变 | +|
| ima_digest_list_pcr | +10 | +在PCR 10中扩展基于摘要列表的IMA度量结果，禁用原生IMA度量 | +
| 11 | +在PCR 11中扩展基于摘要列表的IMA度量结果，禁用原生IMA度量 | +|
| +11 | +在PCR 11中扩展基于摘要列表的IMA度量结果，在PCR 10中扩展原生IMA度量结果 | +|
| ima_digest_db_size | +nn[M] | +设置内核摘要列表上限（0M~64M），不做配置的情况下默认为16MB（不做配置指的是不写该参数，但注意不能将值留空，如ima_digest_db_size=） | +
| ima_capacity | +-1~2147483647 | +设置内核度量日志条数上限，不做配置的情况下默认为100000条，配置-1表示无上限 | +
| initramtmpfs | +无 | +在initrd中支持tmpfs，以携带文件扩展属性 | +
| 参数名称 | +取值 | +功能 | +
|---|---|---|
| -d | +<path> | +指定生成摘要列表文件存放的位置，需为有效目录。 | +
| -f | +compact | +指定生成摘要列表文件的格式，当前仅支持compact格式。 | +
| -i | +<option arg>:<option value> | +指定生成摘要列表的目标文件范围，具体参数定义如下。 | +
| I:<path> | +指定需要生成摘要列表的文件绝对路径，如指定目录，则会执行递归生成。 | +|
| E:<path> | +指定需要排除的路径或目录。 | +|
| F:<path> | +指定路径或目录，为该路径或目录下所有文件生成摘要列表（同时指定e:参数时，忽略e:选项的筛选效果）。 | +|
| e: | +仅对可执行文件生成摘要列表。 | +|
| l:policy | +从系统SELinux策略匹配文件安全上下文，而不是直接从文件扩展属性中读取安全上下文。 | +|
| i: | +当生成metadata类型的摘要列表时，被计算的扩展属性信息包含文件的摘要值（必须指定）。 | +|
| M: | +允许显式指定文件的扩展属性信息（需要结合rpmbuild命令使用）。 | +|
| u: | +将“L:”参数所指定的列表文件名作为生成摘要列表的文件名（需要结合rpmbuild命令使用）。 | +|
| L:<path> | +指定列表文件的路径，列表文件中包含需要生成摘要列表的信息数据（需要结合rpmbuild命令使用）。 | +|
| -o | +add | +指定生成摘要列表的操作，当前仅支持add操作，即将摘要列表添加到文件中。 | +
| -p | +-1 | +指定将摘要列表写入文件中的位置，当前仅支持指定-1。 | +
| -t | +file | +只针对文件内容生成摘要列表。 | +
| metadata | +针对对文件的内容和扩展属性分别生成摘要列表。 | +|
| -T | +NA | +不添加该参数，则生成摘要列表文件，添加该参数则生成TLV摘要列表文件。 | +
| -A | +<path> | +指定相对根目录，将文件路径截去指定的前缀进行路径匹配和SELinux标签匹配。 | +
| -m | +immutable | +指定生成摘要列表文件的modifiers属性，当前仅支持指定immutable。摘要列表在enforce/enforece-evm模式下，摘要列表只能以只读模式打开。 | +
| -h | +NA | +打印帮助信息。 | +
| 关键字 | +值 | +说明 | +
|---|---|---|
| action | +measure | +开启IMA度量 | +
| dont_measure | +禁用IMA度量 | +|
| appraise | +开启IMA评估 | +|
| dont_appraise | +禁用IMA评估 | +|
| audit | +开启审计 | +|
| func | +FILE_CHECK | +将要被打开的文件 | +
| MODULE_CHECK | +将要被装载的内核模块文件 | +|
| MMAP_CHECK | +将要被映射到进程内存空间的动态库文件 | +|
| BRPM_CHECK | +将要被执行的文件（不含通过 /bin/hash 等程序打开的脚本文件） |
+|
| POLICY_CHECK | +将要被导入的IMA策略文件 | +|
| FIRMWARE_CHECK | +将要被加载到内存中的固件 | +|
| DIGEST_LIST_CHECK | +将要被加载到内核中的摘要列表文件 | +|
| KEXEC_KERNEL_CHECK | +将要切换的 kexec 内核 | +|
| mask | +MAY_EXEC | +执行文件 | +
| MAY_WRITE | +写文件 | +|
| MAY_READ | +读文件 | +|
| MAY_APPEND | +扩展文件属性 | +|
| fsmagic | +fsmagic=xxx | +表示文件系统类型的十六进制魔数 | +
| fsuuid | +fsuuid=xxx | +表示系统设备 uuid 的 16 位的十六进制字符串 | +
| fowner | +fowner=xxx | +文件属主的用户 id | +
| uid | +uid=xxx | +操作文件的用户 id | +
| obj_type | +obj_type=xxx_t | +表示文件的类型（基于 SELinux 标签） | +
| pcr | +pcr= |
+选择 TPM 中用于扩展度量值的 PCR（默认为 10） | +
| appraise_type | +imasig | +基于签名进行IMA评估 | +
| meta_immutable | +基于签名进行文件扩展属性的评估（支持摘要列表） | +
+
+其签名机制为：
+
+1) 将CMS签名信息追加到IMA摘要列表文件末尾；
+
+2) 填充结构体并添加到签名信息末尾，结构体定义如下：
+
+```
+struct module_signature {
+ u8 algo; /* Public-key crypto algorithm [0] */
+ u8 hash; /* Digest algorithm [0] */
+ u8 id_type; /* Key identifier type [PKEY_ID_PKCS7] */
+ u8 signer_len; /* Length of signer's name [0] */
+ u8 key_id_len; /* Length of key identifier [0] */
+ u8 __pad[3];
+ __be32 sig_len; /* Length of signature data */
+};
+```
+
+3) 添加魔鬼字符串`"~Module signature appended~\n"`
+
+此步骤的参考脚本如下：
+
+```
+#!/bin/bash
+DIGEST_FILE=$1 # IMA摘要列表文件路径
+SIG_FILE=$2 # IMA摘要列表签名信息保存路径
+OUT=$3 #完成签名信息添加后的摘要列表文件输出路径
+
+cat $DIGEST_FILE $SIG_FILE > $OUT
+echo -n -e "\x00\x00\x02\x00\x00\x00\x00\x00" >> $OUT
+echo -n -e $(printf "%08x" "$(ls -l $SIG_FILE | awk '{print $5}')") | xxd -r -ps >> $OUT
+echo -n "~Module signature appended~" >> $OUT
+echo -n -e "\x0a" >> $OUT
+```
+
+**3) 复用RPM签名（openEuler 22.03 LTS版本默认）**
+
+openEuler 22.03 LTS版本支持复用RPM签名机制实现IMA摘要列表文件的签名。旨在解决版本无专用IMA签名密钥的问题。用户无需感知该签名流程，当RPM包中含有IMA摘要列表文件，而不包含IMA摘要列表的签名文件时，会自动使用该签名机制。其核心原理是通过RPM包的头信息实现对IMA摘要列表的验证。
+
+对于openEuler发布的RPM包，每一个包文件可以包含两部分：
+
+- **RPM头信息：** 存放RPM包属性字段，如包名、文件摘要值列表等，通过RPM头签名保证其完整性；
+- **RPM文件：** 实际安装至系统中的文件，也包括构建阶段生成的IMA摘要列表文件。
+
+
+
+在RPM包安装阶段，如果RPM进程检测到包中的摘要列表文件不包含签名，则在`/etc/ima`目录下创建一个RPM摘要列表文件，将RPM头信息写入文件内容，将RPM头签名写入文件的`security.ima`扩展属性中。后续可通过RPM摘要列表间接实现IMA摘要列表的验证和导入。
+
+##### IMA摘要列表导入
+
+在开启IMA度量模式下，导入IMA摘要列表文件无需经过签名验证，可直接将路径写入内核接口，实现摘要列表的导入/删除：
+
+```
+# 导入IMA摘要列表文件
+echo cat /sys/kernel/security/dim/interval | + +**dim_core状态类型信息说明：** + +状态信息以如下字段取值： + +- DIM_NO_BASELINE：表示dim_core已加载，但未进行任何操作； +- DIM_BASELINE_RUNNING：表示正在进行动态基线建立； +- DIM_MEASURE_RUNNING：表示正在进行动态度量度量； +- DIM_PROTECTED：表示已完成动态基线建立，处于受保护状态； +- DIM_ERROR：执行动态基线建立或动态度量时发生错误，需要用户解决错误后重新触发动态基线建立或动态度量。 + +2. dim_monitor模块接口 + +| 接口名 | 属性 | 说明 | 示例 | +| ---------------------------------- | ---- | ---------------------------------------------- | ------------------------------------------------------------ | +| monitor_run | 只写 | 写入字符串1触发度量，成功返回0，失败返回错误码 | echo 1 > /sys/kernel/security/dim/monitor_run | +| monitor_baseline | 只写 | 写入字符串1触发基线，成功返回0，失败返回错误码 | echo 1 > /sys/kernel/security/dim/monitor_baseline | +| monitor_ascii_runtime_measurements | 只读 | 读取接口查询度量日志 | cat /sys/kernel/security/dim/monitor_ascii_runtime_measurements | +| monitor_status | 只读 | 读取接口返回状态类型信息，失败返回错误码 | cat /sys/kernel/security/dim/monitor_status | + +**dim_monitor状态类型信息说明：** + +- ready：表示dim_monitior已加载，但未进行任何操作； +- running：表示正在进行动态基线建立或动态度量； +- error：执行动态基线建立或动态度量时发生错误，需要用户解决错误后重新触发动态基线建立或动态度量； +- protected：表示已完成动态基线建立，处于受保护状态。 + +#### 用户态工具接口说明 + +dim_gen_baseline命令行接口，详见：
+适配BMC插卡型号：BC83SMMC + +## 应用场景 + +通过TPCM特性构成一个完整的信任链，保障系统启动以后进入一个可信的计算环境。 \ No newline at end of file diff --git "a/docs/zh/docs/Administration/\345\217\257\344\277\241\350\256\241\347\256\227.md" "b/docs/zh/docs/Administration/\345\217\257\344\277\241\350\256\241\347\256\227.md" index efa7a3e9b4116a7ae673abfb29351cd180dd476c..73d88b12b203a3b58c18f11138f15112e446681d 100644 --- "a/docs/zh/docs/Administration/\345\217\257\344\277\241\350\256\241\347\256\227.md" +++ "b/docs/zh/docs/Administration/\345\217\257\344\277\241\350\256\241\347\256\227.md" @@ -2,8 +2,6 @@ ## 可信计算基础 -### 可信计算 - 不同国际组织对可信（Trusted）做了不同的定义。 1. 可信计算组织（TCG）的定义： @@ -25,1809 +23,3 @@  相比于传统安全机制的“头痛医头，脚痛医脚”，发现一个病毒消灭一个病毒，可信计算采用的是白名单机制，即只允许经过认证的内核、内核模块、应用程序等在系统上运行，如果发现程序已发生更改（或本来就是一个未知的程序），就拒绝其执行。 - -## 内核完整性度量（IMA） - -### 概述 - -#### IMA - -IMA，全称 Integrity Measurement Architecture（完整性度量架构），是内核中的一个子系统，能够基于自定义策略对通过 execve()、mmap() 和 open() 系统调用访问的文件进行度量，度量结果可被用于**本地/远程证明**，或者和已有的参考值比较以**控制对文件的访问**。 - -根据 IMA wiki 的定义，内核完整性子系统的功能可以被分为三部分： - -- 度量（measure）：检测对文件的意外或恶意修改，无论远程还是本地。 -- 评估（appraise）：度量文件并与一个存储在扩展属性中的参考值作比较，控制本地文件完整性。 -- 审计（audit）：将度量结果写到系统日志中，用于审计。 - -可以看到，相比于 IMA 度量作为一个“只记录不干涉”的观察员，IMA 评估更像是一位严格的保安人员，它的职责是拒绝对所有“人证不一”的程序的访问。 - -#### EVM - -EVM，全称 Extended Verification Module（扩展验证模块），它的作用就是将系统当中某个文件的安全扩展属性，包括 security.ima 、security.selinux 等合起来计算一个哈希值，然后使用 TPM 中存的密钥或其他可信环境中的密钥对其进行签名，签名之后的值存在 security.evm 中，这个签名后的值是不能被篡改的，如果被篡改，再次访问的时候就会验签失败。 - -总而言之，EVM 的作用就是通过对安全扩展属性计算摘要和签名并将其存储在 security.evm 中，提供对安全扩展属性的离线保护。 - -#### IMA Digest Lists - -IMA Digest Lists（IMA 摘要列表扩展）是 openEuler 对内核原生完整性保护机制的增强，它取代了原生 IMA 机制为文件完整性提供保护。 - -“摘要列表”（digest lists）是一种特殊格式的二进制数据文件，它与 rpm 包一一对应，记录了 rpm 包中受保护文件（即可执行文件和动态库文件）的哈希值。 - -当正确配置启动参数后，内核将维护一个哈希表（对用户空间不可见），并通过 securityfs 对外提供更新哈希表的接口（digest_list_data 和 digest_list_data_del）。摘要列表在构建阶段经过私钥签名，通过接口上传到内核时，需经过内核中的公钥验证。 - - - -在开启 IMA 评估的情况下，每当访问一个可执行文件或动态库文件，就会调用内核中的钩子，计算文件内容和扩展属性的哈希值，并在内核哈希表中进行搜索，如果匹配就允许文件的执行，否则就拒绝访问。 - - - -相比内核社区原生 IMA 机制，openEuler 内核提供的 IMA 摘要列表扩展从安全性、性能、易用性三个方面进行了改良，助力完整性保护机制在生产环境下落地： - -- **具备完整的信任链，安全性好** - - 原生 IMA 机制要求在现网环境下预先生成并标记文件扩展属性，访问文件时将文件扩展属性作为参考值，信任链不完整。 - - IMA 摘要列表扩展将文件参考摘要值保存在内核空间中，构建阶段通过摘要列表的形式携带在发布的 rpm 包中，安装 rpm 包的同时导入摘要列表并执行验签，确保了参考值来自于软件发行商，实现了完整的信任链。 - -- **惊艳的性能** - - 由于 TPM 芯片是一种低速芯片，因此 PCR 扩展操作成为了 IMA 度量场景的性能瓶颈。摘要列表扩展在确保安全性的前提下，减少了不必要的 PCR 扩展操作，相比原生 IMA 性能提升高达 65%。 - - IMA 评估场景下，摘要列表扩展将签名验证统一移动到启动阶段进行，避免每次访问文件时都执行验签，相比原生 IMA 评估场景提升运行阶段文件访问的性能约 20%。 - -- **快速部署，平滑升级** - - 原生 IMA 机制在初次部署或每次更新软件包时，都需要切换到 fix 模式手动标记文件扩展属性后再重启进入 enforce 模式，才能正常访问安装的程序。 - - 摘要列表扩展可实现安装完成后开箱即用，且允许直接在 enforce 模式下安装或升级 rpm 包，无需重启和手动标记即可使用，实现了用户感知最小化，适合现网环境下的快速部署和平滑升级。 - -需要注意的是，IMA 摘要列表扩展将原生 IMA 的验签过程提前到启动阶段进行，也引入了一个假设，即内核空间的内存无法被篡改，这就使得 IMA 也依赖于其他安全机制（内核模块安全启动和内存动态度量）以保护内核内存的完整性。 - -但无论社区原生 IMA 机制还是 IMA 摘要列表扩展，都只是可信计算信任链中的一环，无法孤立地保证系统的安全性，安全自始至终都是一个构建纵深防御的系统工程。 - -### 约束限制 - -1. 当前 IMA 评估模式仅支持保护系统中的不可变文件（包括可执行文件和动态库文件）。 -2. IMA 提供的是应用层的完整性度量，它的安全性依赖于之前环节的可信。 -3. 当前阶段 IMA 不支持第三方应用摘要列表的导入。 -4. 启动日志中可能存在 `Unable to open file: /etc/keys/x509_ima.der` 字样，该报错来自于开源社区，不影响 IMA 摘要列表特性的使用。 -5. ARM 版本中 IMA 开启日志模式可能存在一些 audit 报错信息，这是由于 modprobe 在摘要列表未导入时加载内核模块所致，不影响正常功能。 - -### 使用场景 - -#### IMA measurement - -IMA 度量的目的是检测对系统文件的意外或恶意修改，度量结果可被用于本地证明或远程证明。 - -如果系统中存在 TPM 芯片，度量结果将被扩展到 TPM 芯片的指定 PCR 寄存器中，由于 PCR 扩展的单向性以及 TPM 芯片的硬件安全性，用户无法修改已被扩展的度量结果，这就确保了度量结果的真实性。 - -IMA 度量的文件范围和触发条件可以由用户通过 IMA 策略自行配置。 - -默认情况下 IMA 不启用，但系统会前往 `/etc/ima/` 路径下寻找 ima-policy 策略文件，如果找到，就会按照策略在启动时度量系统中的文件。如果不想手动编写策略文件，也可以在启动参数中配置 `ima_policy=tcb` 使用默认策略（更多策略参数请参考附录“IMA启动参数”章节）。 - -系统当前加载的 IMA 策略可以在 `/sys/kernel/security/ima/policy` 文件中查看，IMA 度量日志则位于`/sys/kernel/security/ima/ascii_runtime_measurements` 文件中，如下所示： - -```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 -``` - -每一条记录从左到右分别是： - -1. PCR：用于扩展度量结果的 PCR 寄存器，默认是 10，只在系统装了 TPM 芯片的情况下有意义。 -2. 模板哈希值：最终被用于扩展的哈希值，组合了文件内容哈希和文件路径的长度和值。 -3. 模板：扩展度量值的模板，如 ima-ng。 -4. 文件内容哈希值：被度量的文件内容的哈希值。 -5. 文件路径：被度量的文件路径。 - -#### IMA appraisal - -IMA 评估的目的是通过与标准参考值的比较，控制对本地文件的访问。 - -IMA 首先使用安全扩展属性 security.ima 和 security.evm 存储文件完整性度量的参考值： - -- security.ima：存储文件内容的哈希值； -- security.evm：存储文件扩展属性的哈希值签名。 - -访问受保护文件时，将会触发内核中的钩子，依次验证文件扩展属性和内容的完整性： - -1. 使用内核 keyring 中的公钥对文件 security.evm 扩展属性中的签名值验签，与当前文件扩展属性的哈希值比较，如果匹配就证明文件的扩展属性是完整的（包括 security.ima）。 -2. 在文件扩展属性完整的前提下，将文件 security.ima 扩展属性的内容与当前文件内容的摘要值比较，如果匹配就允许对文件的访问。 - -同样，IMA 评估的文件范围和触发条件也可以由用户通过 IMA 策略自行配置。 - -#### IMA Digest Lists - -IMA 摘要列表扩展当前提供对以下三种启动参数组合的支持： - -- IMA measurement 度量模式： - - ```shell - ima_policy=exec_tcb ima_digest_list_pcr=11 - ``` - -- IMA appraisal 日志模式 + IMA measurement 度量模式： - - ```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 强制模式 + IMA measurement 度量模式： - - ```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 - ``` - -### 操作指导 - -#### 原生 IMA 场景初次部署 - -第一次启动时，需要在启动参数中配置： - -```shell -ima_appraise=fix ima_policy=appraise_tcb -``` - -`fix` 模式会允许系统在没有参考值的情况下启动，`appraise_tcb` 对应了一种 IMA 策略，具体可参考附录中的“IMA 启动参数”章节。 - -接下来，你需要访问所有需要被校验的文件，从而为它们添加 IMA 扩展属性： - -```shell -# time find / -fstype ext4 -type f -uid 0 -exec dd if='{}' of=/dev/null count=0 status=none \; -``` - -该过程会花费一定时间，请耐心等待。命令执行完成后，你可以从受保护文件的扩展属性中看到参考值已被标记： - -```shell -# getfattr -m - -d /sbin/init -# file: sbin/init -security.ima=0sAXr7Qmun5mkGDS286oZxCpdGEuKT -security.selinux="system_u:object_r:init_exec_t" -``` - -最后，配置以下启动参数并重新启动系统： - -```shell -ima_appraise=enforce ima_policy=appraise_tcb -``` - -#### 摘要列表场景初次部署 - -1. 配置内核参数进入 log 模式。 - - 编辑 `/boot/efi/EFI/openEuler/grub.cfg` 文件，加入以下参数： - - ```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 - ``` - - 使用 `reboot` 重启系统进入 log 模式，该模式下已开启完整性校验，但不会因校验失败而无法启动。 - -2. 安装依赖包。 - - 使用 yum 安装 digest-list-tools 和 ima-evm-utils，确认不低于以下版本： - - ```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. 执行 `dracut` 重新生成 initrd： - - ```shell - # dracut -f -e xattr - ``` - - 编辑 `/boot/efi/EFI/openEuler/grub.cfg` 文件，将 ima_appraise=log 改为 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 - ``` - - 使用 reboot 重启即可完成初次部署。 - -#### 在 OBS 上进行摘要列表构建 - -OBS 全称 Open Build Service，是一种编译系统，最早在 openSUSE 用于软件包的构建，能够支持多架构的分布式编译。 - -进行摘要列表构建之前，首先确保您的工程包含以下 rpm 包，且来自 openEuler： - -- digest-list-tools -- pesign-obs-integration -- selinux-policy -- rpm -- openEuler-rpm-config - -在交付件工程中增加 Project Config： - -```shell -Preinstall: pesign-obs-integration digest-list-tools selinux-policy-targeted -Macros: -%__brp_digest_list /usr/lib/rpm/openEuler/brp-digest-list %{buildroot} -:Macros -``` - -- 在 Preinstall 中新增 digest-list-tools 用于生成摘要列表，pesign-obs-integration 用于生成摘要列表的签名，新增 selinux-policy-targeted 用于确保生成摘要列表时构建环境内 SELinux 标签正确。 -- 在 Macros 中定义宏 %__brp_digest_list，rpm 将在构建阶段通过这个宏执行命令为编译完成的二进制文件生成摘要列表。这个宏可以作为一个开关控制工程中的摘要列表是否生成。 - -配置完成后，OBS 会自动执行全量构建，正常情况下构建完成后，软件包中会新增以下两个文件： - -- /etc/ima/digest_lists/0-metadata_list-compact-[包名]-[版本号] -- /etc/ima/digest_lists.tlv/0-metadata_list-compact_tlv-[包名]-[版本号] - -#### 在 Koji 上进行摘要列表构建 - -Koji 是 Fedora 社区的编译系统，openEuler 社区将在后续支持，敬请期待。 - -### FAQ - -1. 为什么进入 enforce 模式后系统无法启动或启动后命令无法执行/服务不正常？ - - enforce 模式下 IMA 会对文件访问做控制，如果访问文件的内容或扩展属性不完整，就会被拒绝访问，当影响启动的关键命令无法执行时，就会造成系统无法启动。 - - 请确认是否存在以下问题： - - - **摘要列表是否被加入到 initrd 中？** - - 初次部署时是否执行了 dracut 命令将摘要列表加入内核？如果摘要列表没有加入 initrd，启动阶段就无法导入摘要列表，从而导致启动失败。 - - - **是否使用官方提供的 rpm 包？** - - 如果使用的是非 openEuler 官方提供的 rpm 包，rpm 包可能没有携带摘要列表，或者对摘要列表签名的私钥与内核中的验签公钥不匹配，从而导致摘要列表没有被导入内核。 - - 如果原因还不明确，可以进入 log 模式启动，从错误日志中寻找原因： - - ```shell - # dmesg | grep appraise - ``` - -2. 为什么 enforce 模式下没有对系统文件做访问控制？ - - 系统没有按照预期对文件执行访问控制，首先查看启动参数中的 IMA 策略是否已被正确配置： - - ```shell - # cat /proc/cmdline - ...ima_policy=exec_tcb|appraise_exec_tcb|appraise_exec_immutable... - ``` - - 其次查看当前内核中 IMA 策略是否已生效： - - ```shell - # cat /sys/kernel/security/ima/policy - ``` - - 如果 policy 文件是空的，证明策略没有设置成功，系统也就不会进行访问控制。 - -3. 初次部署完成后，安装/升级/卸载软件包后还需要手动执行 dracut 生成 initrd 吗？ - - 不需要。rpm 包提供的 digest_list.so 插件能够在 rpm 包粒度提供摘要列表的自动更新，可以实现用户对摘要列表的无感知。 - -### 附录 - -#### IMA securityfs 接口说明 - -原生 IMA 提供的 securityfs 接口如下： - -> 注：以下接口路径都位于 `/sys/kernel/security/` 目录下。 - -| 路径 | 权限 | 说明 | -| ------------------------------ | ---- | ---------------------------------------- | -| ima/policy | 600 | IMA 策略接口 | -| ima/ascii_runtime_measurement | 440 | ascii 码形式表示的 IMA 度量结果 | -| ima/binary_runtime_measurement | 440 | 二进制形式表示的 IMA 度量结果 | -| ima/runtime_measurement_count | 440 | 度量结果数量统计 | -| ima/violations | 440 | IMA 度量结果冲突数 | -| evm | 660 | EVM 模式，即校验文件扩展属性完整性的方式 | - -其中，`/sys/kernel/security/evm` 的取值有以下三种： - -- 0：EVM 未初始化； -- 1：使用 HMAC（对称加密）方式校验扩展属性完整性； -- 2：使用公钥验签（非对称加密）方式校验扩展属性完整性； -- 6：关闭扩展属性完整性校验（openEuler 使用此方式）。 - -IMA 摘要列表扩展额外提供的 securityfs 接口如下： - -| 路径 | 权限 | 说明 | -| ------------------------ | ---- | --------------------------------------- | -| ima/digests_count | 440 | 显示系统哈希表中的总摘要数量（IMA+EVM） | -| ima/digest_list_data | 200 | 摘要列表新增接口 | -| ima/digest_list_data_del | 200 | 摘要列表删除接口 | - -#### IMA 策略语法 - -每条 IMA 策略语句都必须以 action 关键字代表的**动作**开头，后接**筛选条件**： - -- action：表示该条策略具体的动作，一条策略只能选一个 action。 - - > 注：实际书写时**可忽略 action 字样**，直接书写 dont_measure，不需要写成 action=dont_measure。 - -- func：表示被度量或鉴定的文件类型，常和 mask 匹配使用，一条策略只能选一个 func。 - - - FILE_CHECK 只能同 MAY_EXEC、MAY_WRITE、MAY_READ 匹配使用。 - - MODULE_CHECK、MMAP_CHECK、BPRM_CHECK 只能同 MAY_EXEC 匹配使用。 - - 匹配关系以外的组合不会产生效果。 - -- mask：表示文件在做什么操作时将被度量或鉴定，一条策略只能选一个 mask。 - -- fsmagic：表示文件系统类型的十六进制魔数，定义在 `/usr/include/linux/magic.h` 文件中。 - - > 注：默认情况下度量所有文件系统，除非使用 dont_measure/dont_appraise 标记不度量某文件系统。 - -- fsuuid：表示系统设备 uuid 的 16 位的十六进制字符串。 - -- objtype：表示文件类型，一条策略只能选一个文件类型。 - - > 注：objtype 相比 func 而言，划分的粒度更细，比如 obj_type=nova_log_t 表示 nova log 类型的文件。 - -- uid：表示哪个用户（用用户 id 表示）对文件进行操作，一条策略只能选一个 uid。 - -- fowner：表示文件的属主（用用户 id 表示）是谁，一条策略只能选一个 fowner。 - -关键字的具体取值及说明如下： - -| 关键字 | 值 | 说明 | -| ------ | ---------- | --------- | -| action | measure | 开启 IMA 度量 | -| | dont_measure | 禁用 IMA 度量 | -| | appraise | 开启 IMA 评估 | -| | dont_appraise | 禁用 IMA 评估 | -| | audit | 开启审计 | -| func | FILE_CHECK | 将要被打开的文件 | -| | MODULE_CHECK | 将要被装载的内核模块文件 | -| | MMAP_CHECK | 将要被映射到进程内存空间的动态库文件 | -| | BRPM_CHECK | 将要被执行的文件（不含通过 `/bin/hash` 等程序打开的脚本文件） | -| | POLICY_CHECK | 将要被作为补充 IMA 策略装载的文件 | -| | FIRMWARE_CHECK | 将要被加载到内存中的固件 | -| | DIGEST_LIST_CHECK | 将要被加载到内核中的摘要列表文件 | -| | KEXEC_KERNEL_CHECK | 将要切换的 kexec 内核 | -| mask | MAY_EXEC | 执行文件 | -| | MAY_WRITE | 写文件。不建议使用，受限于 echo、vim 等开源机制（修改本质是新建临时文件再重命名），并不是每次修改都会触发 MAY_WRITE 的 IMA 度量。 | -| | MAY_READ | 读文件 | -| | MAY_APPEND | 扩展文件属性 | -| fsmagic | fsmagic=xxx | 表示文件系统类型的十六进制魔数 | -| fsuuid | fsuuid=xxx | 表示系统设备 uuid 的 16 位的十六进制字符串 | -| fowner | fowner=xxx | 文件属主的用户 id | -| uid | uid=xxx | 操作文件的用户 id | -| obj_type | obj_type=xxx_t | 表示文件的类型（基于 SELinux 标签） | -| pcr | pcr=\
cat /sys/kernel/security/dim/interval | - -**dim_core状态类型信息说明：** - -状态信息以如下字段取值： - -- DIM_NO_BASELINE：表示dim_core已加载，但未进行任何操作； -- DIM_BASELINE_RUNNING：表示正在进行动态基线建立； -- DIM_MEASURE_RUNNING：表示正在进行动态度量度量； -- DIM_PROTECTED：表示已完成动态基线建立，处于受保护状态； -- DIM_ERROR：执行动态基线建立或动态度量时发生错误，需要用户解决错误后重新触发动态基线建立或动态度量。 - -2. dim_monitor模块接口 - -| 接口名 | 属性 | 说明 | 示例 | -| ---------------------------------- | ---- | ---------------------------------------------- | ------------------------------------------------------------ | -| monitor_run | 只写 | 写入字符串1触发度量，成功返回0，失败返回错误码 | echo 1 > /sys/kernel/security/dim/monitor_run | -| monitor_baseline | 只写 | 写入字符串1触发基线，成功返回0，失败返回错误码 | echo 1 > /sys/kernel/security/dim/monitor_baseline | -| monitor_ascii_runtime_measurements | 只读 | 读取接口查询度量日志 | cat /sys/kernel/security/dim/monitor_ascii_runtime_measurements | -| monitor_status | 只读 | 读取接口返回状态类型信息，失败返回错误码 | cat /sys/kernel/security/dim/monitor_status | - -**dim_monitor状态类型信息说明：** - -- ready：表示dim_monitior已加载，但未进行任何操作； -- running：表示正在进行动态基线建立或动态度量； -- error：执行动态基线建立或动态度量时发生错误，需要用户解决错误后重新触发动态基线建立或动态度量； -- protected：表示已完成动态基线建立，处于受保护状态。 - -##### 用户态工具接口说明 - -dim_gen_baseline命令行接口，详见：
-适配BMC插卡型号：BC83SMMC - -### 应用场景 - -通过TPCM特性构成一个完整的信任链，保障系统启动以后进入一个可信的计算环境。 \ No newline at end of file diff --git "a/docs/zh/docs/Administration/\346\220\255\345\273\272repo\346\234\215\345\212\241\345\231\250.md" "b/docs/zh/docs/Administration/\346\220\255\345\273\272repo\346\234\215\345\212\241\345\231\250.md" index 29a1d8a96d3a5d1d44c005c049e7e2f37fa481f2..a00464e11f2cda8b363afe37c13f31da9be093d9 100644 --- "a/docs/zh/docs/Administration/\346\220\255\345\273\272repo\346\234\215\345\212\241\345\231\250.md" +++ "b/docs/zh/docs/Administration/\346\220\255\345\273\272repo\346\234\215\345\212\241\345\231\250.md" @@ -192,6 +192,24 @@ Packages为rpm包所在的目录，repodata为repo源元数据所在的目录， # mkdir -p /usr/share/nginx/uwsgi_temp # mkdir -p /usr/share/nginx/scgi_temp ``` +3. nginx日志转储： + nginx自带日志转储文件：/etc/logrotate.d/nginx，默认每天转储一次，共保留十份转储日志。 + ```shell + #cat /etc/logrotate.d/nginx + /var/log/nginx/*log { + create 0664 nginx root + daily + rotate 10 + missingok + notifempty + compress + sharedscripts + postrotate + /bin/kill -USR1 `cat /run/nginx.pid 2>/dev/null` 2>/dev/null || true + endscript + } + ``` + daily表示每天转储，rotate 10表示保留10份转储日志，用户可以根据自己的需求进行日志转储配置。 ### repo源部署 diff --git "a/docs/zh/docs/Administration/\346\220\255\345\273\272\346\225\260\346\215\256\345\272\223\346\234\215\345\212\241\345\231\250.md" "b/docs/zh/docs/Administration/\346\220\255\345\273\272\346\225\260\346\215\256\345\272\223\346\234\215\345\212\241\345\231\250.md" index c305f5cd18ea9ebdc52e27ee4b259796139f8401..95e60a3973c027ef0a14174fcb8c58afbb3a51e7 100644 --- "a/docs/zh/docs/Administration/\346\220\255\345\273\272\346\225\260\346\215\256\345\272\223\346\234\215\345\212\241\345\231\250.md" +++ "b/docs/zh/docs/Administration/\346\220\255\345\273\272\346\225\260\346\215\256\345\272\223\346\234\215\345\212\241\345\231\250.md" @@ -1,4 +1,5 @@ # 搭建数据库服务器 + - [搭建数据库服务器](#搭建数据库服务器) @@ -20,6 +21,17 @@ - [安装、运行和卸载](#安装运行和卸载-2) - [管理数据库用户](#管理数据库用户-1) - [管理数据库](#管理数据库-2) + - [openGauss服务器](#openGauss服务器) + - [软件介绍](#软件介绍-3) + - [安装](#安装-3) + - [管理数据库角色](#管理数据库角色-1) + - [管理数据库](#管理数据库-3) + - [GreatSQL服务器](#greatsql服务器) + - [软件介绍](#软件介绍-3) + - [配置环境](#配置环境-3) + - [安装、运行和卸载](#安装运行和卸载-3) + - [管理数据库用户](#管理数据库用户-2) + - [管理数据库](#管理数据库-3) @@ -108,7 +120,7 @@ PostgreSQL的架构如[图1](#fig26022387391)所示，主要进程说明如[表1 ### 配置环境 > **说明：** ->以下环境配置仅为参考示例，具体配置视实际需求做配置 +>以下环境配置仅为参考示例，具体配置视实际需求做配置。 #### 关闭防火墙并取消开机自启动 @@ -118,13 +130,13 @@ PostgreSQL的架构如[图1](#fig26022387391)所示，主要进程说明如[表1 1. 在root权限下停止防火墙。 ```shell - # systemctl stop firewalld + systemctl stop firewalld ``` 2. 在root权限下关闭防火墙。 ```shell - # systemctl disable firewalld + systemctl disable firewalld ``` > **说明：** @@ -135,7 +147,7 @@ PostgreSQL的架构如[图1](#fig26022387391)所示，主要进程说明如[表1 在root权限下修改配置文件。 ```shell -# sed -i 's/SELINUX=enforcing/SELINUX=disabled/g' /etc/selinux/config +sed -i 's/SELINUX=enforcing/SELINUX=disabled/g' /etc/selinux/config ``` #### 创建组和用户 @@ -146,39 +158,39 @@ PostgreSQL的架构如[图1](#fig26022387391)所示，主要进程说明如[表1 1. 在root权限下创建PostgreSQL用户（组）。 ```shell - # groupadd postgres - # useradd -g postgres postgres + groupadd postgres + useradd -g postgres postgres ``` 2. 在root权限下设置postgres用户密码（重复输入密码）。 ```shell - # passwd postgres + passwd postgres ``` #### 搭建数据盘 > **说明：** ->- 测试极限性能时，建议单独挂载IO性能更优的NVME SSD存储介质创建PostgreSQL测试实例，避免磁盘IO对性能测试结果的影响，本文以单独挂载NVME SSD为例，参考步骤1\~步骤4。 ->- 非性能测试时，在root权限下执行以下命令，创建数据目录即可。然后跳过本小节： -> mkdir /data +> 测试极限性能时，建议单独挂载IO性能更优的NVME SSD存储介质创建PostgreSQL测试实例，避免磁盘IO对性能测试结果的影响，本文以单独挂载NVME SSD为例，参考步骤1\~步骤4。 +> 非性能测试时，在root权限下执行以下命令，创建数据目录即可。然后跳过本小节： +> mkdir /data 1. 在root权限下创建文件系统（以xfs为例，根据实际需求创建文件系统），若磁盘之前已做过文件系统，执行此命令会出现报错，可使用-f参数强制创建文件系统。 ```shell - # mkfs.xfs /dev/nvme0n1 + mkfs.xfs /dev/nvme0n1 ``` 2. 在root权限下创建数据目录。 ```shell - # mkdir /data + mkdir /data ``` 3. 在root权限下挂载磁盘。 ```shell - # mount -o noatime,nobarrier /dev/nvme0n1 /data + mount -o noatime,nobarrier /dev/nvme0n1 /data ``` #### 数据目录授权 @@ -186,36 +198,36 @@ PostgreSQL的架构如[图1](#fig26022387391)所示，主要进程说明如[表1 1. 在root权限下修改目录权限。 ```shell - # chown -R postgres:postgres /data/ + chown -R postgres:postgres /data/ ``` ### 安装、运行和卸载 #### 安装 -1. 配置本地yum源，详细信息请参考[搭建repo服务器](./搭建repo服务器.html)。 +1. 配置本地yum源，详细信息请参考[搭建repo服务器](./搭建repo服务器.md)。 2. 清除缓存。 ```shell - # dnf clean all + dnf clean all ``` 3. 创建缓存。 ```shell - # dnf makecache + dnf makecache ``` 4. 在root权限下安装PostgreSQL服务器。 ```shell - # dnf install postgresql-server + dnf install postgresql-server ``` 5. 查看安装后的rpm包。 ```shell - # rpm -qa | grep postgresql + rpm -qa | grep postgresql ``` #### 运行 @@ -228,13 +240,13 @@ PostgreSQL的架构如[图1](#fig26022387391)所示，主要进程说明如[表1 1. 切换到已创建的PostgreSQL用户。 ```shell - # su - postgres + su - postgres ``` 2. 初始化数据库，其中命令中的/usr/bin是命令initdb所在的目录。 ```shell - # usr/bin/initdb -D /data/ + usr/bin/initdb -D /data/ ``` ##### 启动数据库 @@ -242,13 +254,13 @@ PostgreSQL的架构如[图1](#fig26022387391)所示，主要进程说明如[表1 1. 启动PostgreSQL数据库。 ```shell - # /usr/bin/pg_ctl -D /data/ -l /data/logfile start + /usr/bin/pg_ctl -D /data/ -l /data/logfile start ``` 2. 确认PostgreSQL数据库进程是否正常启动。 ```shell - # ps -ef | grep postgres + ps -ef | grep postgres ``` 命令执行后，打印信息如下图所示，PostgreSQL相关进程已经正常启动了。 @@ -260,7 +272,7 @@ PostgreSQL的架构如[图1](#fig26022387391)所示，主要进程说明如[表1 1. 登录数据库。 ```shell - # /usr/bin/psql -U postgres + /usr/bin/psql -U postgres ```  @@ -291,7 +303,7 @@ PostgreSQL的架构如[图1](#fig26022387391)所示，主要进程说明如[表1 1. 停止PostgreSQL数据库。 ```shell - # /usr/bin/pg_ctl -D /data/ -l /data/logfile stop + /usr/bin/pg_ctl -D /data/ -l /data/logfile stop ``` #### 卸载 @@ -299,13 +311,13 @@ PostgreSQL的架构如[图1](#fig26022387391)所示，主要进程说明如[表1 1. 在postgres用户下停止数据库。 ```shell - # /usr/bin/pg_ctl -D /data/ -l /data/logfile stop + /usr/bin/pg_ctl -D /data/ -l /data/logfile stop ``` 2. 在root用户下执行**dnf remove postgresql-server**卸载PostgreSQL数据库。 ```shell - # dnf remove postgresql-server + dnf remove postgresql-server ``` ### 管理数据库角色 @@ -355,7 +367,7 @@ postgres=# CREATE ROLE roleexample2 WITH LOGIN PASSWORD '123456'; 创建角色名为roleexample3的角色。 ```shell -[postgres@localhost ~]# createuser roleexample3 +[postgres@localhost ~]# createuser roleexample3 ``` #### 查看角色 @@ -455,7 +467,7 @@ postgres=# DROP ROLE userexample1; 删除userexample2角色。 ```shell -[postgres@localhost ~]# dropuser userexample2 +[postgres@localhost ~]# dropuser userexample2 ``` #### 角色授权 @@ -773,8 +785,8 @@ psql命令不会自动创建databasename数据库，所以在执行psql恢复数 将db1.sql脚本文件导入到主机为192.168.202.144，端口为3306，postgres用户下newdb数据库中。 ```shell -[postgres@localhost ~]# createdb newdb -[postgres@localhost ~]# psql -h 192.168.202.144 -p 3306 -U postgres -W -d newdb < db1.sql +[postgres@localhost ~]# createdb newdb +[postgres@localhost ~]# psql -h 192.168.202.144 -p 3306 -U postgres -W -d newdb < db1.sql ``` ## Mariadb服务器 @@ -819,13 +831,13 @@ MariaDB的架构如[图2](#fig13492418164520)所示。 1. 在root权限下停止防火墙。 ```shell - # systemctl stop firewalld + systemctl stop firewalld ``` 2. 在root权限下关闭防火墙。 ```shell - # systemctl disable firewalld + systemctl disable firewalld ``` > **说明：** @@ -836,7 +848,7 @@ MariaDB的架构如[图2](#fig13492418164520)所示。 1. 在root权限下修改配置文件。 ```shell - # sed -i 's/SELINUX=enforcing/SELINUX=disabled/g' /etc/sysconfig/selinux + sed -i 's/SELINUX=enforcing/SELINUX=disabled/g' /etc/sysconfig/selinux ``` #### 创建组和用户 @@ -847,17 +859,17 @@ MariaDB的架构如[图2](#fig13492418164520)所示。 1. 在root权限下创建MySQL用户（组）。 ```shell - # groupadd mysql + groupadd mysql ``` ```shell - # useradd -g mysql mysql + useradd -g mysql mysql ``` 2. 在root权限下设置MySQL用户密码。 ```shell - # passwd mysql + passwd mysql ``` 重复输入密码（根据实际需求设置密码）。 @@ -865,15 +877,15 @@ MariaDB的架构如[图2](#fig13492418164520)所示。 #### 搭建数据盘 > **说明：** ->- 进行性能测试时，数据目录使用单独硬盘，需要对硬盘进行格式化并挂载，参考方法一或者方法二。 ->- 非性能测试时，在root权限下执行`mkdir /data`创建数据目录即可。然后跳过本小节。 +> 进行性能测试时，数据目录使用单独硬盘，需要对硬盘进行格式化并挂载，参考方法一或者方法二。 +> 非性能测试时，在root权限下执行`mkdir /data`创建数据目录即可。然后跳过本小节。 ##### 方法一：在root权限下使用fdisk进行磁盘管理 1. 创建分区（以/dev/sdb为例，根据实际情况创建） ```shell - # fdisk /dev/sdb + fdisk /dev/sdb ``` 2. 输入n，按回车确认。 @@ -885,17 +897,17 @@ MariaDB的架构如[图2](#fig13492418164520)所示。 8. 创建文件系统（以xfs为例，根据实际需求创建文件系统） ```shell - # mkfs.xfs /dev/sdb1 + mkfs.xfs /dev/sdb1 ``` 9. 挂载分区到“/data”以供操作系统使用。 ```shell - # mkdir /data + mkdir /data ``` ```shell - # mount /dev/sdb1 /data + mount /dev/sdb1 /data ``` 10. 执行命令“vi /etc/fstab", 编辑“/etc/fstab”使重启后自动挂载数据盘。如下图中，添加最后一行内容。 @@ -909,38 +921,38 @@ MariaDB的架构如[图2](#fig13492418164520)所示。 > **说明：** >此步骤需要安装镜像中的lvm2相关包，步骤如下： > ->1. 配置本地yum源，详细信息请参考[搭建repo服务器](./搭建repo服务器.html)。如果已经执行，则可跳过此步。 ->2. 在root权限下执行`yum install lvm2`命令安装lvm2。 +> 配置本地yum源，详细信息请参考[搭建repo服务器](./搭建repo服务器.md)。如果已经执行，则可跳过此步。 +> 在root权限下执行`yum install lvm2`命令安装lvm2。 1. 创建物理卷（sdb为硬盘名称，具体名字以实际为准）。 ```shell - # pvcreate /dev/sdb + pvcreate /dev/sdb ``` 2. 创建物理卷组（其中datavg为创建的卷组名称，具体名字以实际规划为准）。 ```shell - # vgcreate datavg /dev/sdb + vgcreate datavg /dev/sdb ``` 3. 创建逻辑卷（其中600G为规划的逻辑卷大小，具体大小以实际情况为准；datalv为创建的逻辑卷的名字，具体名称以实际规划为准。)。 ```shell - # lvcreate -L 600G -n datalv datavg + lvcreate -L 600G -n datalv datavg ``` 4. 创建文件系统。 ```shell - # mkfs.xfs /dev/datavg/datalv + mkfs.xfs /dev/datavg/datalv ``` 5. 创建数据目录并挂载。 ```shell - # mkdir /data - # mount /dev/datavg/datalv /data + mkdir /data + mount /dev/datavg/datalv /data ``` 6. 执行命令**vi /etc/fstab**，编辑“/etc/fstab”使重启后自动挂载数据盘。如下图中，添加最后一行内容。 @@ -954,39 +966,39 @@ MariaDB的架构如[图2](#fig13492418164520)所示。 1. 在已创建的数据目录 **/data** 基础上，使用root权限继续创建进程所需的相关目录并授权MySQL用户（组）。 ```shell - # mkdir -p /data/mariadb - # cd /data/mariadb - # mkdir data tmp run log - # chown -R mysql:mysql /data + mkdir -p /data/mariadb + cd /data/mariadb + mkdir data tmp run log + chown -R mysql:mysql /data ``` ### 安装、运行和卸载 #### 安装 -1. 配置本地yum源，详细信息请参考[搭建repo服务器](./搭建repo服务器.html)。 +1. 配置本地yum源，详细信息请参考[搭建repo服务器](./搭建repo服务器.md)。 2. 清除缓存。 ```shell - # dnf clean all + dnf clean all ``` 3. 创建缓存。 ```shell - # dnf makecache + dnf makecache ``` 4. 在root权限下安装mariadb服务器。 ```shell - # dnf install mariadb-server + dnf install mariadb-server ``` 5. 查看安装后的rpm包。 ```shell - # rpm -qa | grep mariadb + rpm -qa | grep mariadb ``` #### 运行 @@ -994,13 +1006,13 @@ MariaDB的架构如[图2](#fig13492418164520)所示。 1. 在root权限下开启mariadb服务器。 ```shell - # systemctl start mariadb + systemctl start mariadb ``` 2. 在root权限下初始化数据库。 ```shell - # /usr/bin/mysql_secure_installation + /usr/bin/mysql_secure_installation ``` 命令执行过程中需要输入数据库的root设置的密码，若没有密码则直接按“Enter”。然后根据提示及实际情况进行设置。 @@ -1008,7 +1020,7 @@ MariaDB的架构如[图2](#fig13492418164520)所示。 3. 登录数据库。 ```shell - # mysql -u root -p + mysql -u root -p ``` 命令执行后提示输入密码。密码为[2](#li197143190587)中设置的密码。 @@ -1021,14 +1033,14 @@ MariaDB的架构如[图2](#fig13492418164520)所示。 1. 在root权限下关闭数据库进程。 ```shell - # ps -ef | grep mysql - # kill -9 进程ID + ps -ef | grep mysql + kill -9 进程ID ``` 2. 在root权限下执行**dnf remove mariadb-server**命令卸载mariadb。 ```shell - # dnf remove mariadb-server + dnf remove mariadb-server ``` ### 管理数据库用户 @@ -1363,31 +1375,31 @@ mysqldump [options] -all-databases > outputfile 备份主机为192.168.202.144，端口为3306，root用户下的所有数据库到alldb.sql中。 ```shell -# mysqldump -h 192.168.202.144 -P 3306 -uroot -p123456 --all-databases > alldb.sql +mysqldump -h 192.168.202.144 -P 3306 -uroot -p123456 --all-databases > alldb.sql ``` 备份主机为192.168.202.144，端口为3306，root用户下的db1数据库到db1.sql中。 ```shell -# mysqldump -h 192.168.202.144 -P 3306 -uroot -p123456 --databases db1 > db1.sql +mysqldump -h 192.168.202.144 -P 3306 -uroot -p123456 --databases db1 > db1.sql ``` 备份主机为192.168.202.144，端口为3306，root用户下的db1数据库的tb1表到db1tb1.sql中。 ```shell -# mysqldump -h 192.168.202.144 -P 3306 -uroot -p123456 db1 tb1 > db1tb1.sql +mysqldump -h 192.168.202.144 -P 3306 -uroot -p123456 db1 tb1 > db1tb1.sql ``` 只备份主机为192.168.202.144，端口为3306，root用户下的db1数据库的表结构到db1.sql中。 ```shell -# mysqldump -h 192.168.202.144 -P 3306 -uroot -p123456 -d db1 > db1.sql +mysqldump -h 192.168.202.144 -P 3306 -uroot -p123456 -d db1 > db1.sql ``` 只备份主机为192.168.202.144，端口为3306，root用户下的db1数据库的数据到db1.sql中。 ```shell -# mysqldump -h 192.168.202.144 -P 3306 -uroot -p123456 -t db1 > db1.sql +mysqldump -h 192.168.202.144 -P 3306 -uroot -p123456 -t db1 > db1.sql ``` #### 恢复数据库 @@ -1440,13 +1452,13 @@ MySQL所使用的SQL语言是用于访问数据库的最常用标准化语言。 1. 在root权限下停止防火墙。 ```shell - # systemctl stop firewalld + systemctl stop firewalld ``` 2. 在root权限下关闭防火墙。 ```shell - # systemctl disable firewalld + systemctl disable firewalld ``` > **说明：** @@ -1457,7 +1469,7 @@ MySQL所使用的SQL语言是用于访问数据库的最常用标准化语言。 1. 在root权限下修改配置文件。 ```shell - # sed -i 's/SELINUX=enforcing/SELINUX=disabled/g' /etc/sysconfig/selinux + sed -i 's/SELINUX=enforcing/SELINUX=disabled/g' /etc/sysconfig/selinux ``` #### 创建组和用户 @@ -1468,17 +1480,17 @@ MySQL所使用的SQL语言是用于访问数据库的最常用标准化语言。 1. 在root权限下创建MySQL用户（组）。 ```shell - # groupadd mysql + groupadd mysql ``` ```shell - # useradd -g mysql mysql + useradd -g mysql mysql ``` 2. 在root权限下设置MySQL用户密码。 ```shell - # passwd mysql + passwd mysql ``` 重复输入密码（根据实际需求设置密码）。 @@ -1487,14 +1499,14 @@ MySQL所使用的SQL语言是用于访问数据库的最常用标准化语言。 > **说明：** >- 进行性能测试时，数据目录使用单独硬盘，需要对硬盘进行格式化并挂载，参考方法一或者方法二。 ->- 非性能测试时，在root权限下执行`mkdir /data`创建数据目录即可。然后跳过本小节： +>- 非性能测试时，在root权限下执行`mkdir /data`创建数据目录即可。然后跳过本小节： ##### 方法一：在root权限下使用fdisk进行磁盘管理 1. 创建分区（以/dev/sdb为例，根据实际情况创建） ```shell - # fdisk /dev/sdb + fdisk /dev/sdb ``` 2. 输入n，按回车确认。 @@ -1506,17 +1518,17 @@ MySQL所使用的SQL语言是用于访问数据库的最常用标准化语言。 8. 创建文件系统（以xfs为例，根据实际需求创建文件系统） ```shell - # mkfs.xfs /dev/sdb1 + mkfs.xfs /dev/sdb1 ``` 9. 挂载分区到“/data”以供操作系统使用。 ```shell - # mkdir /data + mkdir /data ``` ```shell - # mount /dev/sdb1 /data + mount /dev/sdb1 /data ``` 10. 执行命令“vi /etc/fstab", 编辑“/etc/fstab”使重启后自动挂载数据盘。如下图中，添加最后一行内容。 @@ -1529,41 +1541,41 @@ MySQL所使用的SQL语言是用于访问数据库的最常用标准化语言。 > **说明：** >此步骤需要安装镜像中的lvm2相关包，步骤如下： ->1. 配置本地yum源，详细信息请参考[搭建repo服务器](./搭建repo服务器.html)。如果已经执行，则可跳过此步。 ->2. 执行`yum install lvm2`安装lvm2。 +> 配置本地yum源，详细信息请参考[搭建repo服务器](./搭建repo服务器.md)。如果已经执行，则可跳过此步。 +> 执行`yum install lvm2`安装lvm2。 1. 创建物理卷（sdb为硬盘名称，具体名字以实际为准）。 ```shell - #pvcreate /dev/sdb + pvcreate /dev/sdb ``` 2. 创建物理卷组（其中datavg为创建的卷组名称，具体名字以实际规划为准）。 ```shell - #vgcreate datavg /dev/sdb + vgcreate datavg /dev/sdb ``` 3. 创建逻辑卷（其中600G为规划的逻辑卷大小，具体大小以实际情况为准；datalv为创建的逻辑卷的名字，具体名称以实际规划为准。)。 ```shell - #lvcreate -L 600G -n datalv datavg + lvcreate -L 600G -n datalv datavg ``` 4. 创建文件系统。 ```shell - #mkfs.xfs /dev/datavg/datalv + mkfs.xfs /dev/datavg/datalv ``` 5. 创建数据目录并挂载。 ```shell - #mkdir /data + mkdir /data ``` ```shell - #mount /dev/datavg/datalv /data + mount /dev/datavg/datalv /data ``` 6. 执行命令**vi /etc/fstab**，编辑“/etc/fstab”使重启后自动挂载数据盘。如下图中，添加最后一行内容。 @@ -1577,39 +1589,39 @@ MySQL所使用的SQL语言是用于访问数据库的最常用标准化语言。 1. 在已创建的数据目录 **/data** 基础上，使用root权限继续创建进程所需的相关目录并授权MySQL用户（组）。 ```shell - # mkdir -p /data/mysql - # cd /data/mysql - # mkdir data tmp run log - # chown -R mysql:mysql /data + mkdir -p /data/mysql + cd /data/mysql + mkdir data tmp run log + chown -R mysql:mysql /data ``` ### 安装、运行和卸载 #### 安装 -1. 配置本地yum源，详细信息请参考[搭建repo服务器](./搭建repo服务器.html)章节。 +1. 配置本地yum源，详细信息请参考[搭建repo服务器](./搭建repo服务器.md)章节。 2. 清除缓存。 ```shell - # dnf clean all + dnf clean all ``` 3. 创建缓存。 ```shell - # dnf makecache + dnf makecache ``` 4. 在root权限下安装MySQL服务器。 ```shell - # dnf install mysql-server + dnf install mysql-server ``` 5. 查看安装后的rpm包。 ```shell - # rpm -qa | grep mysql-server + rpm -qa | grep mysql-server ``` #### 运行 @@ -1618,7 +1630,7 @@ MySQL所使用的SQL语言是用于访问数据库的最常用标准化语言。 1. 在root权限下创建my.cnf文件，其中文件路径（包括软件安装路径basedir、数据路径datadir等）根据实际情况修改。 ```shell - # vi /etc/my.cnf + vi /etc/my.cnf ``` 编辑my.cnf内容如下： @@ -1646,7 +1658,7 @@ MySQL所使用的SQL语言是用于访问数据库的最常用标准化语言。 2. 确保my.cnf配置文件修改正确。 ```shell - # cat /etc/my.cnf + cat /etc/my.cnf ```  @@ -1657,14 +1669,14 @@ MySQL所使用的SQL语言是用于访问数据库的最常用标准化语言。 3. 在root权限下修改/etc/my.cnf文件的组和用户为mysql:mysql ```shell - # chown mysql:mysql /etc/my.cnf + chown mysql:mysql /etc/my.cnf ``` 2. 配置环境变量。 1. 安装完成后，在root权限下将MySQL二进制文件路径到PATH。 ```shell - # echo export PATH=$PATH:/usr/local/mysql/bin >> /etc/profile + echo export PATH=$PATH:/usr/local/mysql/bin >> /etc/profile ``` > **注意：** @@ -1673,13 +1685,13 @@ MySQL所使用的SQL语言是用于访问数据库的最常用标准化语言。 2. 在root权限下使环境变量配置生效。 ```shell - # source /etc/profile + source /etc/profile ``` 3. 在root权限下初始化数据库。 > **说明：** - >本步骤倒数第2行中有初始密码，请注意保存，登录数据库时需要使用。 + >本步骤倒数第2行中有初始密码，请注意保存，登录数据库时需要使用。 ```shell # mysqld --defaults-file=/etc/my.cnf --initialize @@ -1698,22 +1710,22 @@ MySQL所使用的SQL语言是用于访问数据库的最常用标准化语言。 1. 在root权限下修改文件权限。 ```shell - # chmod 777 /usr/local/mysql/support-files/mysql.server - # chown mysql:mysql /var/log/mysql/* + chmod 777 /usr/local/mysql/support-files/mysql.server + chown mysql:mysql /var/log/mysql/* ``` 2. 在root权限下启动MySQL。 ```shell - # cp /usr/local/mysql/support-files/mysql.server /etc/init.d/mysql - # chkconfig mysql on + cp /usr/local/mysql/support-files/mysql.server /etc/init.d/mysql + chkconfig mysql on ``` 以mysql用户启动数据库。 ```shell - # su - mysql - # service mysql start + su - mysql + service mysql start ``` 5. 登录数据库。 @@ -1765,14 +1777,14 @@ MySQL所使用的SQL语言是用于访问数据库的最常用标准化语言。 1. 在root权限下关闭数据库进程。 ```shell - # ps -ef | grep mysql - # kill -9 进程ID + ps -ef | grep mysql + kill -9 进程ID ``` 2. 在root权限下执行**dnf remove mysql**命令卸载MySQL。 ```shell - # dnf remove mysql + dnf remove mysql ``` ### 管理数据库用户 @@ -2104,31 +2116,1232 @@ mysqldump [options] -all-databases > outputfile 备份主机为192.168.202.144，端口为3306，root用户下的所有数据库到alldb.sql中。 ```shell -# mysqldump -h 192.168.202.144 -P 3306 -uroot -p123456 --all-databases > alldb.sql +mysqldump -h 192.168.202.144 -P 3306 -uroot -p123456 --all-databases > alldb.sql +``` + +备份主机为192.168.202.144，端口为3306，root用户下的db1数据库到db1.sql中。 + +```shell +mysqldump -h 192.168.202.144 -P 3306 -uroot -p123456 --databases db1 > db1.sql +``` + +备份主机为192.168.202.144，端口为3306，root用户下的db1数据库的tb1表到db1tb1.sql中。 + +```shell +mysqldump -h 192.168.202.144 -P 3306 -uroot -p123456 db1 tb1 > db1tb1.sql +``` + +只备份主机为192.168.202.144，端口为3306，root用户下的db1数据库的表结构到db1.sql中。 + +```shell +mysqldump -h 192.168.202.144 -P 3306 -uroot -p123456 -d db1 > db1.sql +``` + +只备份主机为192.168.202.144，端口为3306，root用户下的db1数据库的数据到db1.sql中。 + +```shell +mysqldump -h 192.168.202.144 -P 3306 -uroot -p123456 -t db1 > db1.sql +``` + +#### 恢复数据库 + +可以在root权限下使用mysql命令恢复数据库。 + +恢复一个或多个表： + +```shell +mysql -h hostname -P portnumber -u username -ppassword databasename < infile +``` + +其中： + +- hostname：主机名。 +- portnumber：端口号。 +- username：用户名。 +- password：密码。 +- databasename：数据库名。 +- infile：mysqldump命令中的outfile参数。 + +##### 示例 + +恢复数据库。 + +```shell +# mysql -h 192.168.202.144 -P 3306 -uroot -p123456 -t db1 < db1.sql +``` + +## openGauss服务器 + +### 软件介绍 + +openGauss是一款开源关系型数据库管理系统，采用木兰宽松许可证v2发行。openGauss内核深度融合华为在数据库领域多年的经验，结合企业级场景需求，持续构建竞争力特性。 + +### 安装 + +安装指南请参见[《openGauss rpm安装》](https://docs.opengauss.org/zh/docs/latest/docs/InstallationGuide/RPM%E5%AE%89%E8%A3%85.html)。 + +### 管理数据库角色 + +#### 创建角色 + +可以使用CREATE ROLE语句来创建角色，在数据库界面执行。 + +```shell +CREATE ROLE role_name [ [ WITH ] option [ ... ] ] [ ENCRYPTED | UNENCRYPTED ] { PASSWORD | IDENTIFIED BY } { 'password' [EXPIRED] | DISABLE }; +``` + +其中： + +- role_name：角色名。 +- password：登录密码。 +- option为参数选项，常用的有： + - SYSADMIN | NOSYSADMIN：决定一个新角色是否为"系统管理员"，具有SYSADMIN属性的角色拥有系统最高权限。缺省为NOSYSADMIN。 + - CREATEDB | NOCREATEDB：定义一个角色是否能创建数据库，若未指定，则默认为NOCREATEDB，即不能创建数据库。 + - CREATEROLE | NOCREATEROLE：决定一个角色是否可以创建新角色，若未指定，则默认为NOCREATEROLE，即不能创建新角色。 + - INHERIT | NOINHERIT：这些子句决定一个角色是否“继承”它所在组的角色的权限。不推荐使用。 + - LOGIN | NOLOGIN：具有LOGIN属性的角色才可以登录数据库。一个拥有LOGIN属性的角色可以认为是一个用户。 + - ENCRYPTED | UNENCRYPTED：控制密码存储在系统表里的口令是否加密。按照产品安全要求，密码必须加密存储，所以，UNENCRYPTED在openGauss中禁止使用。因为系统无法对指定的加密口令字符串进行解密，所以如果目前的口令字符串已经是用SHA256加密的格式，则会继续照此存放，而不管是否声明了ENCRYPTED或UNENCRYPTED。这样就允许在dump/restore的时候重新加载加密的口令。 + - VALID UNTIL：设置角色失效的时间戳。如果省略了该子句，角色无有效结束时间限制。 + - IN ROLE：新角色立即拥有IN ROLE子句中列出的一个或多个现有角色拥有的权限。不推荐使用。 + - ROLE：ROLE子句列出一个或多个现有的角色，它们将自动添加为这个新角色的成员，拥有新角色所有的权限。 + +要使用这条命令，必须拥有 CREATE ROLE 权限或者是系统管理员。 + +##### 示例 + +创建一个角色，名为manager，密码为xxxxxxxxx。 + +```shell +openGauss=# CREATE ROLE manager IDENTIFIED BY 'xxxxxxxxx'; +``` + +创建一个角色，从2015年1月1日开始生效，到2026年1月1日失效。 + +```shell +openGauss=# CREATE ROLE miriam WITH LOGIN PASSWORD 'xxxxxxxxx' VALID BEGIN '2015-01-01' VALID UNTIL '2026-01-01'; +``` + +#### 查看角色 + +可以使用SELECT语句或gsql的元命令du或者du+查看角色。 + +```shell +SELECT * FROM pg_roles; +``` + +```shell +\du +``` + +```shell +\du+ +``` + +##### 示例 + +查看所有角色名包括内置角色。 + +```shell +openGauss=# SELECT rolname from pg_roles; +``` + +查看现有角色不包含内置角色。 + +```shell +openGauss=# \du +``` + +#### 修改角色 + +##### 修改用户名 + +可以使用ALTER ROLE语句修改一个已经存在的角色名。 + +```shell +ALTER ROLE oldrolename RENAME TO newrolename; +``` + +其中： + +- oldrolename：旧的角色名。 +- newrolename：新的角色名。 + +##### 修改用户示例 + +将角色名manager修改为newmanager。 + +```shell +openGauss=# ALTER ROLE manager RENAME TO newmanager; +``` + +##### 修改用户密码 + +可以使用ALTER ROLE语句修改一个角色的登录密码。 + +```shell +ALTER ROLE rolename with PASSWORD 'password' +``` + +其中： + +- rolename：角色名。 +- password：密码。 + +##### 修改角色密码示例 + +将manager的密码修改为xxxxxxxxx。 + +```shell +openGauss=# ALTER ROLE manager with PASSWORD 'xxxxxxxxx'; +``` + +#### 删除角色 + +可以使用DROP ROLE语句来删除角色。在数据库界面执行。 + +```shell +DROP ROLE rolename; +``` + +其中：rolename为角色名。 + +##### 示例 + +删除manager角色。 + +```shell +openGauss=# DROP ROLE manager; +``` + +#### 角色授权 + +可以使用GRANT语句来对角色授权。 + +对角色授予表或视图的操作权限： + +```shell +GRANT { { SELECT | INSERT | UPDATE | DELETE | TRUNCATE | REFERENCES | TRIGGER | ALTER | DROP | COMMENT | INDEX | VACUUM } [, ...] + | ALL [ PRIVILEGES ] } + ON { [ TABLE ] table_name [, ...] + | ALL TABLES IN SCHEMA schema_name [, ...] } + TO { [ GROUP ] role_name | PUBLIC } [, ...] + [ WITH GRANT OPTION ]; +``` + +对角色授予序列的操作权限： + +```shell +GRANT { { SELECT | UPDATE | USAGE | ALTER | DROP | COMMENT } [, ...] + | ALL [ PRIVILEGES ] } + ON { [ [ LARGE ] SEQUENCE ] sequence_name [, ...] + | ALL SEQUENCES IN SCHEMA schema_name [, ...] } + TO { [ GROUP ] role_name | PUBLIC } [, ...] + [ WITH GRANT OPTION ]; +``` + +对角色授予数据库的操作权限： + +```shell +GRANT { { CREATE | CONNECT | TEMPORARY | TEMP | ALTER | DROP | COMMENT } [, ...] + | ALL [ PRIVILEGES ] } + ON DATABASE database_name [, ...] + TO { [ GROUP ] role_name | PUBLIC } [, ...] + [ WITH GRANT OPTION ]; +``` + +对角色授予函数的操作权限： + +```shell +GRANT { { EXECUTE | ALTER | DROP | COMMENT } [, ...] | ALL [ PRIVILEGES ] } + ON { FUNCTION {function_name ( [ {[ argmode ] [ arg_name ] arg_type} [, ...] ] )} [, ...] + | ALL FUNCTIONS IN SCHEMA schema_name [, ...] } + TO { [ GROUP ] role_name | PUBLIC } [, ...] + [ WITH GRANT OPTION ]; +``` + +对角色授予过程语言的操作权限： + +```shell +GRANT { USAGE | ALL [ PRIVILEGES ] } + ON LANGUAGE lang_name [, ...] + TO { [ GROUP ] role_name | PUBLIC } [, ...] + [ WITH GRANT OPTION ]; +``` + +将模式的访问权限赋予指定的角色： + +```shell +GRANT { { CREATE | USAGE | ALTER | DROP | COMMENT } [, ...] | ALL [ PRIVILEGES ] } + ON SCHEMA schema_name [, ...] + TO { [ GROUP ] role_name | PUBLIC } [, ...] + [ WITH GRANT OPTION ]; +``` + +对角色授予表空间的操作权限： + +```shell +GRANT { { CREATE | ALTER | DROP | COMMENT } [, ...] | ALL [ PRIVILEGES ] } + ON TABLESPACE tablespace_name [, ...] + TO { [ GROUP ] role_name | PUBLIC } [, ...] + [ WITH GRANT OPTION ]; +``` + +将角色rolename1的成员关系赋予角色rolename2： + +```shell +GRANT rolename1 [, ...] TO rolename2 [, ...] [ WITH ADMIN OPTION ] +``` + +其中： + +- SELECT、INSERT、UPDATE、DELETE、REFERENCES、TRIGGER、USAGE、CREATE、CONNECT、TEMPORARY、TEMP、EXECUTE、ALL PRIVILEGES：用户的操作权限，ALL PRIVILEGES表示所有的权限。 +- ON字句：用于指定权限授予的对象。 +- tablename：表名。 +- TO字句：用来指定被赋予权限的角色。 +- rolename1、rolename2：角色名。 +- PUBLIC：表示该权限要赋予所有角色，包括那些以后可能创建的用户。 +- WITH GRANT OPTION：被授权的用户也可以将此权限赋予他人，否则就不能授权给他人。这个选项不能赋予PUBLIC。 +- sequence_name：序列名。 +- database_name：数据库名。 +- function_name ( [ {[ argmode ] [ arg_name ] arg_type} [, ...] ] )} [, ...]：函数名及其参数。 +- lang_name：过程语言名。 +- schema_name：模式名。 +- tablespace_name：表空间名。 +- WITH ADMIN OPTION：表示成员随后就可以将角色的成员关系赋予其他角色，以及撤销其他角色的成员关系。 + +##### 示例 + +对manager授予数据库database1的CREATE权限。· + +```shell +openGauss=# GRANT CREATE ON DATABASE database1 TO manager; +``` + +对所有用户授予表table1的所有权限。 + +```shell +openGauss=# GRANT ALL PRIVILEGES ON TABLE table1 TO PUBLIC; +``` + +#### 删除用户权限 + +可以使用REVOKE语句来撤销一个或多个角色的权限。 + +撤销角色对表的操作权限： + +```shell +REVOKE [ GRANT OPTION FOR ] + { { SELECT | INSERT | UPDATE | DELETE | TRUNCATE | REFERENCES | ALTER | DROP | COMMENT | INDEX | VACUUM }[, ...] + | ALL [ PRIVILEGES ] } + ON { [ TABLE ] table_name [, ...] + | ALL TABLES IN SCHEMA schema_name [, ...] } + FROM { [ GROUP ] role_name | PUBLIC } [, ...] + [ CASCADE | RESTRICT ]; +``` + +撤销角色对序列的操作权限： + +```shell +REVOKE [ GRANT OPTION FOR ] + { { SELECT | UPDATE | ALTER | DROP | COMMENT }[, ...] + | ALL [ PRIVILEGES ] } + ON { [ [ LARGE ] SEQUENCE ] sequence_name [, ...] + | ALL SEQUENCES IN SCHEMA schema_name [, ...] } + FROM { [ GROUP ] role_name | PUBLIC } [, ...] + [ CASCADE | RESTRICT ]; +``` + +撤销角色对数据库的操作权限： + +```shell +REVOKE [ GRANT OPTION FOR ] + { { CREATE | CONNECT | TEMPORARY | TEMP | ALTER | DROP | COMMENT } [, ...] + | ALL [ PRIVILEGES ] } + ON DATABASE database_name [, ...] + FROM { [ GROUP ] role_name | PUBLIC } [, ...] + [ CASCADE | RESTRICT ]; +``` + +撤销角色对函数的操作权限： + +```shell +REVOKE [ GRANT OPTION FOR ] + { { EXECUTE | ALTER | DROP | COMMENT } [, ...] | ALL [ PRIVILEGES ] } + ON { FUNCTION {function_name ( [ {[ argmode ] [ arg_name ] arg_type} [, ...] ] )} [, ...] + | ALL FUNCTIONS IN SCHEMA schema_name [, ...] } + FROM { [ GROUP ] role_name | PUBLIC } [, ...] + [ CASCADE | RESTRICT ]; +``` + +撤销角色对过程语言的操作权限： + +```shell +REVOKE [ GRANT OPTION FOR ] + { USAGE | ALL [ PRIVILEGES ] } + ON LANGUAGE lang_name [, ...] + FROM { [ GROUP ] role_name | PUBLIC } [, ...] + [ CASCADE | RESTRICT ]; +``` + +撤销角色对模式的操作权限： + +```shell +REVOKE [ GRANT OPTION FOR ] + { { CREATE | USAGE | ALTER | DROP | COMMENT } [, ...] | ALL [ PRIVILEGES ] } + ON SCHEMA schema_name [, ...] + FROM { [ GROUP ] role_name | PUBLIC } [, ...] + [ CASCADE | RESTRICT ]; + +``` + +撤销角色对表空间的操作权限： + +```shell +REVOKE [ GRANT OPTION FOR ] + { { CREATE | ALTER | DROP | COMMENT } [, ...] | ALL [ PRIVILEGES ] } + ON TABLESPACE tablespace_name [, ...] + FROM { [ GROUP ] role_name | PUBLIC } [, ...] + [ CASCADE | RESTRICT ]; +``` + +删除rolename2的rolename1之间的成员关系： + +```shell +REVOKE [ ADMIN OPTION FOR ] rolename1 [, ...] FROM rolename2 [, ...] [ CASCADE | RESTRICT ] +``` + +其中： + +- GRANT OPTION FOR：表示只是撤销对该权限的授权的权力，而不是撤销该权限本身。 +- SELECT、INSERT、UPDATE、DELETE、REFERENCES、TRIGGER、USAGE、CREATE、CONNECT、TEMPORARY、TEMP、EXECUTE、ALL PRIVILEGES：用户的操作权限，ALL PRIVILEGES表示所有的权限。 +- ON字句：用于指定撤销权限的对象。 +- table_name：表名。 +- FROM字句：用来指定被撤销权限的角色。 +- rolename1、rolename2：角色名。 +- PUBLIC：表示撤销隐含定义的、拥有所有角色的组，但并不意味着所有角色都失去了权限，那些直接得到的权限以及通过一个组得到的权限仍然有效。 +- sequence_name：序列名。 +- CASCADE：撤销所有依赖性权限。 +- RESTRICT：不撤销所有依赖性权限。 +- database_name：数据库名。 +- function_name ( [ {[ argmode ] [ arg_name ] arg_type} [, ...] ] )} [, ...]：函数名及其参数。 +- lang_name：过程语言名。 +- schema_name：模式名。 +- tablespace_name：表空间名。 +- ADMIN OPTION FOR：表示传递的授权不会自动收回。 + +##### 示例 + +对manager授予数据库database1的CREATE权限。 + +```shell +openGauss=# GRANT CREATE ON DATABASE database1 TO manager; +``` + +对所有用户撤销表table1的所有权限。 + +```shell +openGauss=# REVOKE ALL PRIVILEGES ON TABLE table1 FROM PUBLIC; +``` + +### 管理数据库 + +#### 创建数据库 + +可以使用CREATE DATABASE语句来创建数据库。在数据库界面使用。 + +```shell +CREATE DATABASE databasename; +``` + +其中：databasename为数据库名。 + +要使用这条命令，必须拥有CREATEDB权限。 + +##### 示例 + +创建一个数据库database1。 + +```shell +openGauss=# CREATE DATABASE database1; +``` + +#### 选择数据库 + +可以使用\c语句来选择数据库。 + +```shell +\c databasename; +``` + +其中：databasename为数据库名称。 + +##### 示例 + +选择database_example数据库。 + +```shell +openGauss=# \c database_example; +``` + +#### 查看数据库 + +可以使用\l语句来查看数据库。 + +```shell +\l; +``` + +##### 示例 + +查看所有数据库。 + +```shell +openGauss=# \l; +``` + +#### 删除数据库 + +可以使用DROP DATABASE语句来删除数据库。 + +> **注意：** +>删除数据库要谨慎操作，一旦删除，数据库中的所有表和数据都会删除。 + +```shell +DROP DATABASE databasename; +``` + +其中：databasename为数据库名称。 + +DROP DATABASE会删除数据库的系统目录项并且删除包含数据的文件目录。 + +DROP DATABASE只能由超级管理员或数据库管理者执行。 + +##### 示例 + +删除databaseexample数据库。 + +```shell +openGauss=# DROP DATABASE databaseexample; +``` + +#### 备份数据库 + +gs_dump支持将数据库信息导出至纯文本格式的SQL脚本文件或其他归档文件中。 + +```shell +gs_dump [OPTION]... [DBNAME] +gs_dump -p port_number postgres -f dump1.sql +``` + +其中： + +- DBNAME前面不需要加短或长选项。DBNAME指定要连接的数据库。 例如： 不需要-d，直接指定DBNAME。 +- dump1.sql：数据库备份的文件。 +- option：gs_dump命令参数选项，多个参数之间可以使用空格分隔。常用的gs_dump命令参数选项如下： + - -F, --format=c|d|t|p：选择输出格式。格式如下： + - p|plain：输出一个文本SQL脚本文件（默认）。 + - c|custom：输出一个自定义格式的归档，并且以目录形式输出，作为gs_restore输入信息。该格式是最灵活的输出格式，因为能手动选择，而且能在恢复过程中将归档项重新排序。该格式默认状态下会被压缩。 + - d|directory：该格式会创建一个目录，该目录包含两类文件，一类是目录文件，另一类是每个表和blob对象对应的数据文件。 + - t|tar：输出一个tar格式的归档形式，作为gs_restore输入信息。tar格式与目录格式兼容；tar格式归档形式在提取过程中会生成一个有效的目录格式归档形式。但是，tar格式不支持压缩且对于单独表有8GB的大小限制。此外，表数据项的相应排序在恢复过程中不能更改. + - -h, --host=HOSTNAME：指定主机名。 + - -p, --port=PORT：指定端口。 + - -U, --username=NAME：指定连接的用户名。 + - -W, --password=PASSWORD：指定用户连接的密码。如果主机的认证策略是trust，则不会对系统管理员进行密码验证，即无需输入-W选项；如果没有-W选项，并且不是系统管理员，“Dump Restore工具”会提示用户输入密码。 + - -w, --no-password：不出现输入密码提示。如果主机要求密码认证并且密码没有通过其它形式给出，则连接尝试将会失败。 该选项在批量工作和不存在用户输入密码的脚本中很有帮助。 + +##### 示例 + +执行gs_dump，导出postgres数据库全量信息，导出的MPPDB_backup.sql文件格式为纯文本格式。 + +```shell +[openGauss@localhost ~]# gs_dump -U omm -W password -f backup/MPPDB_backup.sql -p port postgres -F p +``` + +执行gs_dump，导出postgres数据库全量信息，导出的MPPDB_backup.dmp文件格式为自定义归档格式。 + +```shell +gs_dump -U omm -W password -f backup/MPPDB_backup.dmp -p port postgres -F c +``` + +#### 恢复数据库 + +gs_restore是openGauss提供的针对gs_dump导出数据的导入工具。通过此工具可将由gs_dump生成的导出文件进行导入。 + +```shell +gs_restore [OPTION]... FILE +``` + +其中： + +- FILE没有短选项或长选项。用来指定归档文件所处的位置。 +- 作为前提条件，需输入dbname或-l选项。不允许用户同时输入dbname和-l选项。 +- gs_restore默认是以追加的方式进行数据导入。为避免多次导入造成数据异常，在进行导入时，建议使用“-c” 参数，在重新创建数据库对象前，清理（删除）已存在于将要还原的数据库中的数据库对象。 +- option：通用参数如下： + - -f，--file=FILENAME：指定生成脚本的输出文件，或使用-l时列表的输出文件。 + - -d, --dbname=NAME：连接数据库dbname并直接导入到该数据库中。 + - -h, --host=HOSTNAME：指定主机名。 + - -p, --port=PORT：指定端口。 + - -U, --username=NAME：指定连接的用户名。 + - -W, --password=PASSWORD：指定用户连接的密码。如果主机的认证策略是trust，则不会对系统管理员进行密码验证，即无需输入-W参数；如果没有-W参数，并且不是系统管理员，“gs_restore”会提示用户输入密码。 + +##### 示例 + +执行gs_restore，将导出的MPPDB_backup.dmp文件（自定义归档格式）导入到postgres数据库。 + +```shell +[openGauss@localhost ~]# gs_restore -W password backup/MPPDB_backup.dmp -p port -d postgres +``` + +## GreatSQL服务器 + +### 软件介绍 + +GreatSQL 数据库是开放原子开源基金会旗下捐赠项目，拥有中国信通院可信开源社区+可信开源项目双认证。 + +GreatSQL 数据库是一款 **开源免费** 数据库，可在普通硬件上满足金融级应用场景，具有 **高可用**、**高性能**、**高兼容**、**高安全** 等特性，可作为 MySQL 或 Percona Server for MySQL 的理想可选替换。 + +GreatSQL 致力于保持开源的开放性。GreatSQL 采用 [GPLv2 协议](https://gitee.com/GreatSQL/GreatSQL/blob/master/LICENSE)。 + +GreatSQL 数据库由 [GreatSQL 社区](https://greatsql.cn) 主导负责运营维护，已有[众多社区维护者、爱好者及用户](https://greatsql.cn/docs/community/6-thanks.html)参与，包括提交代码、功能测试验证、发现 Bug 以及文档改进等多方面贡献。 + +### 配置环境 + +> **说明：** +>以下环境配置仅为参考示例，具体配置视实际需求做配置 + +#### 关闭防火墙并取消开机自启动 + +> **说明：** +>测试环境下通常会关闭防火墙以避免部分网络因素影响，视实际需求做配置。 + +1. 在root权限下停止防火墙。 + + ```shell + systemctl stop firewalld + ``` + +2. 在root权限下关闭防火墙。 + + ```shell + systemctl disable firewalld + ``` + + > **说明：** + >执行disable命令关闭防火墙的同时，也取消了开机自启动。 + +#### 修改SELINUX为disabled + +1. 在root权限下修改配置文件。 + + ```shell + sed -i 's/SELINUX=enforcing/SELINUX=disabled/g' /etc/sysconfig/selinux + ``` + +#### 创建组和用户 + +> **说明：** +>服务器环境下，为了系统安全，通常会为进程分配单独的用户，以实现权限隔离。本章节创建的组和用户都是操作系统层面的，不是数据库层面的。 + +在root权限下创建MySQL用户（组）。 + +```shell +groupadd mysql +``` + +```shell +useradd -r -g mysql -s /sbin/nologin mysql +``` + +#### 搭建数据盘 + +> **说明：** +> 测试极限性能时，建议单独挂载IO性能更优的NVME SSD存储介质创建GreatSQL测试实例，避免磁盘IO对性能测试结果的影响，本文以单独挂载NVME SSD为例，参考步骤1\~步骤4。 +> 非性能测试时，在root权限下执行以下命令，创建数据目录即可。然后跳过本小节： +> mkdir /data + +1. 在root权限下创建文件系统（以xfs为例，根据实际需求创建文件系统），若磁盘之前已做过文件系统，执行此命令会出现报错，可使用-f参数强制创建文件系统。 + + ```shell + mkfs.xfs /dev/nvme0n1 + ``` + +2. 在root权限下创建数据目录。 + + ```shell + mkdir /data + ``` + +3. 在root权限下挂载磁盘。 + + ```shell + mount -o noatime,nobarrier /dev/nvme0n1 /data + ``` + +#### 创建数据库目录 + +在已创建的数据目录 **/data** 基础上，使用root权限继续创建进程所需的相关目录并授权MySQL用户（组）。 + +```shell +mkdir -p /data/GreatSQL +cd /data/GreatSQL +chown -R mysql:mysql /data/GreatSQL +``` + +### 安装、运行和卸载 + +#### 安装 + +> **注意：** +> 安装GreatSQL前请先检查是否已先安装了MySQL/Percona Server For MySQL/MariaDB等这些MySQL同态数据库，如果已经安装需要先卸载，否则无法再安装GreatSQL，会产生冲突。 + +1. 配置本地yum源，详细信息请参考[搭建repo服务器](./搭建repo服务器.md)章节。 + +2. 清除缓存。 + + ```shell + dnf clean all + ``` + +3. 创建缓存。 + + ```shell + dnf makecache + ``` + +4. 在root权限下安装MySQL服务器。 + + ```shell + dnf install greatsql-server + ``` + + 如果安装时遇到冲突报错，需要先卸载MySQL/Percona Server For MySQL/MariaDB等MySQL同态数据库。 + +5. 查看安装后的rpm包。 + + ```shell + rpm -qa | grep greatsql-server + ``` + +#### 运行 + +1. 在root权限下修改/etc/my.cnf文件，包括软件安装路径basedir、数据路径datadir、监听端口号port、内存缓冲区innodb_buffer_pool_size等根据实际情况修改。 + + ```shell + vi /etc/my.cnf + ``` + + 编辑/etc/my.cnf内容如下（下面是一个最基本参考）： + + ```shell + [client] + datadir = /data/GreatSQL/mysql.sock + + [mysqld] + !includedir /etc/my.cnf.d + user = mysql + datadir = /data/GreatSQL + socket = /data/GreatSQL/mysql.sock + log-error = /data/GreatSQL/mysqld.log + pid-file = /data/GreatSQL/mysqld.pid + slow_query_log = ON + long_query_time = 0.01 + log_slow_verbosity = FULL + log_error_verbosity = 3 + innodb_buffer_pool_size = 1G + innodb_redo_log_capacity = 256M + innodb_io_capacity = 10000 + innodb_io_capacity_max = 20000 + innodb_flush_sync = OFF + ``` + + 如果想要让GreatSQL获得更好的运行状态和性能，可以参考GreatSQL社区提供的[my.cnf配置文件参考模板](https://gitee.com/GreatSQL/GreatSQL-Doc/blob/master/docs/my.cnf-example)。 + +2. 确保my.cnf配置文件修改正确。 + + ```shell + cat /etc/my.cnf + ``` + +  + +3. 在root权限下启动GreatSQL数据库。 + + ```shell + systemctl start mysqld + ``` + + 首次启动会比较慢，可能需要数分钟，因为包含初始化GreatSQL数据库的工作。 + + 待初始化完成后，查看`datadir`配置参数对应的目录下是否已有数据文件，以及相应的日志文件`/data/GreatSQL/mysqld.log`。 + + ```shell + ls -la /data/GreatSQL + ``` + + 查看`/data/GreatSQL/mysqld.log`日志文件，若其中包括“Bootstrapping complete”表示初始化数据库完成，且包含“A temporary password is generated for root@localhost: =dz;kqt8svrF”这样的信息，则其中的“=dz;kqt8svrF”为GreatSQL数据库root账户的初始密码，第一次登入后要立即修改才能继续使用GreatSQL。 + +4. 登录数据库。 + + > **说明：** + >- 提示输入密码时，请输入[步骤4](#li15634560588)产生的初始密码。 + + ```shell + mysql -uroot -p + ``` + +  + +5. 修改初始化密码 + + 如上面截图所示，首次登录GreatSQL数据库后，需要先修改临时初始密码才能继续后面的操作。 + + ```shell + greatsql [(none)]> \s + ERROR 1820 (HY000): You must reset your password using ALTER USER statement before executing this statement. + greatsql [(none)]> ALTER USER USER() IDENTIFIED BY 'GreatSQL@202X'; + Query OK, 0 rows affected (0.00 sec) + ``` + +6. 创建一个允许从任何服务器访问的数据库账户GreatSQL，并授权允许该账户对名为test的数据库下所有数据对象的所有操作权限 + + ```shell + -- 在这里指定新账户GreatSQL的密码为"GreatSQL-202X"，建议修改成您自己设定成其他密码 + greatsql [(none)]> CREATE USER GreatSQL@'%' IDENTIFIED BY 'GreatSQL-202X'; + Query OK, 0 rows affected (0.00 sec) + + greatsql [(none)]> GRANT ALL ON test.* TO GreatSQL@'%'; + Query OK, 0 rows affected (0.00 sec) + ``` + +7. 创建名为test的新数据库 + + ```shell + greatsql [(none)]> CREATE DATABASE test; + Query OK, 1 row affected (0.00 sec) + ``` + +8. 退出数据库。 + + 执行 `\q` 或者 `exit` 退出数据库。 + + ```shell + greatsql> exit + ``` + +9. 切换新创建的GreatSQL账户登录，并操作数据库 + + ```shell + -- 这里使用上面创建GreatSQL新账户时指定的密码 "GreatSQL-202X"，或者修改成您自己设定的密码 + -- 后面指定test是指登录后立即使用test数据库，要带空格，否则会被认为是密码 + mysql -uGreatSQL -p test + Enter password: + ... + + -- 创建新表 + greatsql [test]> CREATE TABLE t1(id INT PRIMARY KEY); + Query OK, 0 rows affected (1.48 sec) + + -- 查看都有哪些数据表 + greatsql [test]> SHOW TABLES; + +----------------+ + | Tables_in_test | + +----------------+ + | t1 | + +----------------+ + 1 row in set (0.00 sec) + + -- 写入测试数据 + greatsql [test]> INSERT INTO t1 SELECT RAND()*1024; + Query OK, 1 row affected (0.34 sec) + Records: 1 Duplicates: 0 Warnings: 0 + + -- 查询数据 + greatsql [test]> SELECT * FROM t1; + +-----+ + | id | + +-----+ + | 565 | + +-----+ + 1 row in set (0.00 sec) + ``` + +这就完成了对GreatSQL数据库的基本操作。 + +更多相关SQL命令/语法详见手册：[SQL Statements](https://dev.mysql.com/doc/refman/8.0/en/sql-statements.html)。 + +更多基于 GreatSQL 的应用开发内容请参考：[应用开发](https://greatsql.cn/docs/12-dev-guide/12-dev-guide.html)。 + +#### 卸载GreatSQL + +1. 在root权限下关闭数据库进程。 + + ```shell + systemctl stop mysqld + ``` + +2. 在root权限下执行**dnf remove -y greatsql-server**命令卸载GreatSQL。 + + ```shell + dnf remove -y greasql-server + ``` + +### 管理数据库用户 + +#### 创建用户 + +可以使用CREATE USER语句来创建一个或多个用户，并设置相应的口令。 + +```shell +CREATE USER 'username'@'hostname' IDENTIFIED BY 'password'; +``` + +其中： + +- username：用户名。 +- host：主机名，即用户连接数据库时所在的主机的名字。若是本地用户可用localhost，若在创建的过程中，未指定主机名，则主机名默认为“%”，表示一组主机。 +- password：用户的登录密码，密码可以为空，如果为空则该用户可以不需要密码登录服务器，但从安全的角度而言，不推荐这种做法。 + +使用CREATE USER语句必须拥有数据库的INSERT权限或全局CREATE USER权限。 + +使用CREATE USER语句创建一个用户帐号后，会在系统自身的数据库的user表中添加一条新记录。若创建的帐户已经存在，则语句执行时会出现错误。 + +新创建的用户拥有的权限很少，只允许进行不需要权限的操作，如使用SHOW语句查询所有存储引擎和字符集的列表等。 + +##### 示例 + +创建密码为"GreatSQL@202X-local"，用户名为**GreatSQL_local**的本地用户。 + +```shell +CREATE USER GreatSQL_local@localhost IDENTIFIED BY 'GreatSQL@202X'; +``` + +创建密码为"GreatSQL@202X-remote"，用户名为**GreatSQL_remote**，主机名为**192.168.1.100**的用户。 + +```shell +CREATE USER 'GreatSQL_remote'@'192.168.1.100' IDENTIFIED BY 'GreatSQL@202X-remote'; +``` + +#### 查看用户 + +可以使用SHOW GRANTS语句或SELECT语句查看一个或多个用户。 + +查看特定用户： + +```shell +SHOW GRANTS [FOR 'username'@'hostname']; +``` + +```shell +SELECT USER,HOST,PASSWORD FROM mysql.user WHERE USER='username'; +``` + +查看所有用户： + +```shell +SELECT USER,HOST FROM mysql.user; +``` + +其中： + +- username：用户名。 +- hostname：主机名。 + +##### 示例 + +查看userexample1用户。 + +```sql +SHOW GRANTS FOR GreatSQL; ++----------------------------------------------------+ +| Grants for GreatSQL@% | ++----------------------------------------------------+ +| GRANT USAGE ON *.* TO `GreatSQL`@`%` | +| GRANT ALL PRIVILEGES ON `test`.* TO `GreatSQL`@`%` | ++----------------------------------------------------+ +2 rows in set (0.00 sec) +``` + +#### 修改用户 + +##### 修改用户名 + +可以使用RENAME USER语句修改一个或多个已经存在的用户名。 + +```shell +RENAME USER 'oldusername'@'hostname' TO 'newusername'@'hostname'; +``` + +其中： + +- oldusername：旧的用户名。 +- newusername：新的用户名。 +- hostname：主机名。 + +RENAME USER语句用于对原有的帐号进行重命名。若系统中旧帐号不存在或者新帐号已存在，则该语句执行时会出现错误。 + +使用RENAME USER语句，必须拥有数据库的UPDATE权限或全局CREATE USER权限。 + +##### 修改用户示例 + +将用户名userexample1修改为userexapme2，主机名为locahost。 + +```shell +> RENAME USER 'userexample1'@'localhost' TO 'userexample2'@'localhost'; +``` + +##### 修改用户密码 + +可以使用SET PASSWORD语句修改一个用户的登录密码。 + +```shell +SET PASSWORD FOR 'username'@'hostname' = 'newpassword'; +``` + +其中： + +- FOR 'username'@'hostname'：FOR字句，可选项，指定欲修改密码的用户名及主机名。 +- 'newpassword'：新密码。 + +在SET PASSWORD语句中，若不加上FOR子句，表示修改当前用户的密码。 + +FOR字句中必须以'username'@'hostname'的格式给定，username为帐户的用户名，hostname为帐户的主机名。 + +欲修改密码的帐号必须在系统中存在，否则语句执行时会出现错误。 + +**建议**：更推荐使用`ALTER USER`命令来修改数据库中的账号密码。 + +##### 修改用户密码示例 + +将用户名为GreatSQL_remote的密码修改为"GreatSQL@@202X-remote"。 + +```shell +SET PASSWORD FOR 'GreatSQL_remote'@'192.168.1.100' = 'GreatSQL@@202X-remote'; +``` + +#### 删除用户 + +可以使用DROP USER语句来删除一个或多个用户帐号以及相关的权限。 + +```shell +DROP USER 'username1'@'hostname1' [,'username2'@'hostname2']…; +``` + +> **注意：** +>用户的删除不会影响他们之前所创建的表、索引或其他数据库对象，因为数据库并不会记录创建了这些对象的帐号。 + +DROP USER语句可用于删除一个或多个数据库帐号，并删除其原有权限。 + +使用DROP USER语句必须拥有数据库的DELETE权限或全局CREATE USER权限。 + +在DROP USER语句的使用中，若没有明确地给出帐号的主机名，则该主机名默认为“%”。 + +##### 示例 + +删除用户名为userexample的本地用户。 + +```shell +DROP USER 'userexample'@'localhost'; +``` + +#### 用户授权 + +可以使用GRANT语句来对新建用户的授权。 + +```shell +GRANT privileges ON databasename.tablename TO 'username'@'hostname'; +``` + +其中： + +- ON字句：用于指定权限授予的对象和级别。 +- privileges：用户的操作权限，如SELECT，INSERT，UPDATE等，如果要授予所有的权限则使用ALL。 +- databasename：数据库名。 +- tablename：表名。 +- TO字句：用来设定用户密码，以及指定被赋予权限的用户。 +- username：用户名。 +- hostname：主机名。 + +如果要授予该用户对所有数据库和表的相应操作权限则可用\*表示，如\*.\*。 + +如果在TO子句中给系统中存在的用户指定密码，则新密码会将原密码覆盖。 + +如果权限被授予给一个不存在的用户，则会自动执行一条CREATE USER语句来创建这个用户，但同时必须为该用户指定密码。 + +##### 示例 + +对本地用户userexample授予SELECT和INSERT权限。 + +```shell +GRANT SELECT,INSERT ON *.* TO 'userexample'@'localhost'; +``` + +#### 回收用户权限 + +可以使用REVOKE语句来回收一个用户的权限，但此用户不会被删除。 + +```shell +REVOKE privilege ON databasename.tablename FROM 'username'@'hostname'; +``` + +其中REVOKE语句的参数与GRANT语句的参数含义相同。 + +要使用 REVOKE 语句，必须拥有数据库的全局CREATE USER权限或UPDATE权限。 + +##### 示例 + +回收本地用户userexample的INSERT权限。 + +```shell +REVOKE INSERT ON *.* FROM 'userexample'@'localhost'; +``` + +### 管理数据库 + +#### 创建数据库 + +可以使用CREATE DATABASE语句来创建数据库。 + +```shell +CREATE DATABASE databasename; +``` + +其中：databasename为数据库名称，且数据库名称不区分大小写。 + +##### 示例 + +创建数据库名为databaseexample的数据库。 + +```shell +CREATE DATABASE databaseexample; +``` + +#### 查看数据库 + +可以使用SHOW DATABASES语句来查看数据库。 + +```shell +SHOW DATABASES; +``` + +##### 示例 + +查看所有数据库。 + +```shell +SHOW DATABASES; +``` + +#### 选择数据库 + +一般创建表，查询表等操作首先需要选择一个目标数据库。可以使用USE语句来选择数据库。 + +```shell +USE databasename; +``` + +其中：databasename为数据库名称。 + +##### 示例 + +选择databaseexample数据库。 + +```shell +USE databaseexample; +``` + +#### 删除数据库 + +可以使用DROP DATABASE语句来删除数据库。 + +> **注意：** +>删除数据库要谨慎操作，一旦删除，数据库中的所有表和数据都会删除。 + +```shell +DROP DATABASE databasename; +``` + +其中：databasename为数据库名称。 + +DROP DATABASE命令用于删除创建过\(已存在\)的数据库，且会删除数据库中的所有表，但数据库的用户权限不会自动删除。 + +要使用DROP DATABASE，您需要数据库的DROP权限。 + +DROP SCHEMA是DROP DATABASE的同义词。 + +##### 示例 + +删除databaseexample数据库。 + +```shell +DROP DATABASE databaseexample; +``` + +#### 备份数据库 + +可以在root权限下使用mysqldump命令备份数据库。 + +备份一个或多个表： + +```shell +mysqldump [options] databasename [tablename ...] > outfile +``` + +备份一个或多个库： + +```shell +mysqldump [options] -databases databasename ... > outfile +``` + +备份所有库： + +```shell +mysqldump [options] -all-databases > outputfile +``` + +其中： + +- databasename：数据库名称。 +- tablename：数据表名称。 +- outfile：数据库备份的文件。 +- options：mysqldump命令参数选项，多个参数之间可以使用空格分隔。常用的mysqldump命令参数选项如下： + - -u, \-\-user= _username_ ：指定用户名。 + - -p, \-\-password\[= _password_\]：指定密码，在下面的例子中密码都指定为123456，您需要根据实际情况调整。 + - -P, \-\-port= _portnumber_ ：指定端口。 + - -h, \-\-host= _hostname_ ：指定主机名。 + - -r, \-\-result-file= _filename_ ：将导出结果保存到指定的文件中，等同于“\>”。 + - -t：只备份数据。 + - -d：只备份表结构。 + +##### 示例 + +备份主机为192.168.202.144，端口为3306，root用户下的所有有权限读取的数据库到alldb.sql中。 + +```shell +mysqldump -h 192.168.202.144 -P 3306 -uroot -p123456 --all-databases > alldb.sql ``` 备份主机为192.168.202.144，端口为3306，root用户下的db1数据库到db1.sql中。 ```shell -# mysqldump -h 192.168.202.144 -P 3306 -uroot -p123456 --databases db1 > db1.sql +mysqldump -h 192.168.202.144 -P 3306 -uroot -p123456 --databases db1 > db1.sql ``` 备份主机为192.168.202.144，端口为3306，root用户下的db1数据库的tb1表到db1tb1.sql中。 ```shell -# mysqldump -h 192.168.202.144 -P 3306 -uroot -p123456 db1 tb1 > db1tb1.sql +mysqldump -h 192.168.202.144 -P 3306 -uroot -p123456 db1 tb1 > db1tb1.sql ``` 只备份主机为192.168.202.144，端口为3306，root用户下的db1数据库的表结构到db1.sql中。 ```shell -# mysqldump -h 192.168.202.144 -P 3306 -uroot -p123456 -d db1 > db1.sql +mysqldump -h 192.168.202.144 -P 3306 -uroot -p123456 -d db1 > db1.sql ``` 只备份主机为192.168.202.144，端口为3306，root用户下的db1数据库的数据到db1.sql中。 ```shell -# mysqldump -h 192.168.202.144 -P 3306 -uroot -p123456 -t db1 > db1.sql +mysqldump -h 192.168.202.144 -P 3306 -uroot -p123456 -t db1 > db1.sql ``` #### 恢复数据库 diff --git "a/docs/zh/docs/Administration/\346\237\245\347\234\213\347\263\273\347\273\237\344\277\241\346\201\257.md" "b/docs/zh/docs/Administration/\346\237\245\347\234\213\347\263\273\347\273\237\344\277\241\346\201\257.md" index e35099b2b02326ad921af2cc586443c25a23deab..e52582d12020ca81b006d444ac5c0b522020a177 100644 --- "a/docs/zh/docs/Administration/\346\237\245\347\234\213\347\263\273\347\273\237\344\277\241\346\201\257.md" +++ "b/docs/zh/docs/Administration/\346\237\245\347\234\213\347\263\273\347\273\237\344\277\241\346\201\257.md" @@ -3,7 +3,7 @@ - 查看系统信息，命令如下： ```shell - cat /etc/os-release + $ cat /etc/os-release ``` 例如，命令和输出如下： @@ -23,23 +23,23 @@ 查看CPU信息，命令如下： ```shell - # lscpu + $ lscpu ``` 查看内存信息，命令如下： ```shell - free + $ free ``` 查看磁盘信息，命令如下： ```shell - fdisk -l + $ fdisk -l ``` - 查看系统资源实时信息，命令如下： ```shell - top + $ top ``` diff --git "a/docs/zh/docs/Administration/\350\277\234\347\250\213\350\257\201\346\230\216\357\274\210\351\262\262\351\271\217\345\256\211\345\205\250\345\272\223\357\274\211.md" "b/docs/zh/docs/Administration/\350\277\234\347\250\213\350\257\201\346\230\216\357\274\210\351\262\262\351\271\217\345\256\211\345\205\250\345\272\223\357\274\211.md" new file mode 100644 index 0000000000000000000000000000000000000000..e3ccf7f0e6c364098b8d55b58b43175d78402a1a --- /dev/null +++ "b/docs/zh/docs/Administration/\350\277\234\347\250\213\350\257\201\346\230\216\357\274\210\351\262\262\351\271\217\345\256\211\345\205\250\345\272\223\357\274\211.md" @@ -0,0 +1,400 @@ +# 远程证明（鲲鹏安全库） + +## 介绍 + +本项目开发运行在鲲鹏处理器上的基础安全软件组件，前期主要聚焦在远程证明等可信计算相关领域，使能社区安全开发者。 + +## 软件架构 + +在未使能TEE的平台上，本项目可提供平台远程证明特性，其软件架构如下图所示： + + + +在已使能TEE的平台上，本项目可提供TEE远程证明特性，其软件架构如下图所示： + + + +## 安装配置 + +1. 使用yum安装程序的rpm包，命令如下： + + ```shell + # yum install kunpengsecl-ras kunpengsecl-rac kunpengsecl-rahub kunpengsecl-qcaserver kunpengsecl-attester kunpengsecl-tas kunpengsecl-devel + ``` + +2. 准备数据库环境：进入 `/usr/share/attestation/ras` 目录，执行 `prepare-database-env.sh` 脚本进行自动化的数据库环境配置。 + +3. 程序运行时依赖的配置文件有三个路径，分别为：当前路径 `./config.yaml` ，家路径 `${HOME}/.config/attestation/ras(rac)(rahub)(qcaserver)(attester)(tas)/config.yaml` ，以及系统路径 `/etc/attestation/ras(rac)(rahub)(qcaserver)(attester)(tas)/config.yaml` 。 + +4. （可选）如果需要创建家目录配置文件，可在安装好rpm包后，执行位于 `/usr/share/attestation/ras(rac)(rahub)(qcaserver)(attester)(tas)` 下的脚本 `prepare-ras(rac)(hub)(qca)(attester)(tas)conf-env.sh` 从而完成家目录配置文件的部署。 + +## 相关参数 + +### RAS启动参数 + +命令行输入 `ras` 即可启动RAS程序。请注意，在当前目录下需要提供**ECDSA**公钥并命名为 `ecdsakey.pub` 。相关参数如下： + +```shell + -H --https http/https模式开关，默认为https(true)，false=http + -h --hport https模式下RAS监听的restful api端口 + -p, --port string RAS监听的client api端口 + -r, --rest string http模式下RAS监听的restful api端口 + -T, --token 生成一个测试用的验证码并退出 + -v, --verbose 打印更详细的RAS运行时日志信息 + -V, --version 打印RAS版本并退出 +``` + +### RAC启动参数 + +命令行输入 `sudo raagent` 即可启动RAC程序，请注意，物理TPM模块的开启需要sudo权限。相关参数如下： + +```shell + -s, --server string 指定待连接的RAS服务端口 + -t, --test 以测试模式启动 + -v, --verbose 打印更详细的RAC运行时日志信息 + -V, --version 打印RAC版本并退出 + -i, --imalog 指定ima文件路径 + -b, --bioslog 指定bios文件路径 + -T, --tatest 以TA测试模式启动 +``` + +**注意：** +>1.若要使用TEE远程证明特性，需要以非TA测试模式启动RAC，并将待证明TA的uuid、是否使用TCB、mem_hash和img_hash按序放入RAC执行路径下的**talist**文件内。同时预装由TEE团队提供的**libqca.so**库和**libteec.so**库。**talist**文件格式如下： +> +>```text +>e08f7eca-e875-440e-9ab0-5f381136c600 false ccd5160c6461e19214c0d8787281a1e3c4048850352abe45ce86e12dd3df9fde 46d5019b0a7ffbb87ad71ea629ebd6f568140c95d7b452011acfa2f9daf61c7a +>``` +> +>2.若不使用TEE远程证明特性，则需要将 `/usr/share/attestation/qcaserver` 目录下的libqca.so库和libteec.so库复制到 `/usr/lib` 或 `/usr/lib64` 目录，并以TA测试模式启动RAC。 + +### QCA启动参数 + +命令行输入 `/usr/bin/qcaserver` 即可启动QCA程序，请注意，这里必须要使用qcaserver的完整路径以正常启动QTA，同时需要使QTA中的CA路径参数与该路径保持相同。相关参数如下： + +```shell + -C, --scenario int 设置程序的应用场景，默认为no_as场景(0)，1=as_no_daa场景，2=as_with_daa场景 + -S, --server string 指定开放的服务器地址/端口 +``` + +### ATTESTER启动参数 + +命令行输入 `attester` 即可启动ATTESTER程序。相关参数如下： + +```shell + -B, --basevalue string 设置基准值文件读取路径 + -M, --mspolicy int 设置度量策略，默认为-1，需要手动指定。1=仅比对img-hash值，2=仅比对hash值，3=同时比对img-hash和hash两个值 + -S, --server string 指定待连接的服务器地址 + -U, --uuid int 指定待验证的可信应用 + -V, --version 打印程序版本并退出 + -T, --test 读取固定的nonce值以匹配目前硬编码的可信报告 +``` + +### TAS启动参数 + +命令行输入 `tas` 即可启动TAS程序。相关参数如下： + +```shell + -T, --token 生成一个测试用的验证码并退出 +``` + +**注意：** +>1.若要启用TAS服务，需要先为TAS配置好私钥。可以按如下命令修改家目录下的配置文件： +> +>```shell +># cd ${HOME}/.config/attestation/tas +># vim config.yaml +> # 如下DAA_GRP_KEY_SK_X和DAA_GRP_KEY_SK_Y的值仅用于测试，正常使用前请务必更新其内容以保证安全。 +>tasconfig: +> port: 127.0.0.1:40008 +> rest: 127.0.0.1:40009 +> akskeycertfile: ./ascert.crt +> aksprivkeyfile: ./aspriv.key +> huaweiitcafile: ./Huawei IT Product CA.pem +> DAA_GRP_KEY_SK_X: 65a9bf91ac8832379ff04dd2c6def16d48a56be244f6e19274e97881a776543c65a9bf91ac8832379ff04dd2c6def16d48a56be244f6e19274e97881a776543c +> DAA_GRP_KEY_SK_Y: 126f74258bb0ceca2ae7522c51825f980549ec1ef24f81d189d17e38f1773b56126f74258bb0ceca2ae7522c51825f980549ec1ef24f81d189d17e38f1773b56 +>``` +> +>之后再输入`tas`启动TAS程序。 +> +>2.在有TAS环境中，为提高QCA配置证书的效率，并非每一次启动都需要访问TAS以生成相应证书，而是通过证书的本地化存储，即读取QCA侧 `config.yaml` 中配置的证书路径，通过 `func hasAKCert(s int) bool` 函数检查是否已有TAS签发的证书保存于本地，若成功读取证书，则无需访问TAS，若读取证书失败，则需要访问TAS，并将TAS返回的证书保存于本地。 + +## 接口定义 + +### RAS接口 + +为了便于管理员对目标服务器、RAS以及目标服务器上部署的TEE中的用户 TA 进行管理，本程序设计了以下接口可供调用： + +| 接口 | 方法 | +| --------------------------------- | --------------------------- | +| / | GET | +| /{id} | GET、POST、DELETE | +| /{from}/{to} | GET | +| /{id}/reports | GET | +| /{id}/reports/{reportid} | GET、DELETE | +| /{id}/basevalues | GET | +| /{id}/newbasevalue | POST | +| /{id}/basevalues/{basevalueid} | GET、POST、DELETE | +| /{id}/ta/{tauuid}/status | GET | +| /{id}/ta/{tauuid}/tabasevalues | GET | +| /{id}/ta/{tauuid}/tabasevalues/{tabasevalueid} | GET、POST、DELETE | +| /{id}/ta/{tauuid}/newtabasevalue | POST | +| /{id}/ta/{tauuid}/tareports | GET | +| /{id}/ta/{tauuid}/tareports/{tareportid} | GET、POST、DELETE | +| /{id}/basevalues/{basevalueid} | GET、DELETE | +| /version | GET | +| /config | GET、POST | +| /{id}/container/status | GET | +| /{id}/device/status | GET | + +上述接口的具体用法分别介绍如下。 + +若需要查询所有服务器的信息，可以使用`"/"`接口。 + +```shell +# curl -X GET -H "Content-Type: application/json" http://localhost:40002/ +``` + +*** +若需要查询目标服务器的详细信息，可以使用`"/{id}"`接口的`GET`方法，其中{id}是RAS为目标服务器分配的唯一标识号。 + +```shell +# curl -X GET -H "Content-Type: application/json" http://localhost:40002/1 +``` + +*** +若需要修改目标服务器的信息，可以使用`"/{id}"`接口的`POST`方法，其中$AUTHTOKEN是事先使用`ras -T`自动生成的身份验证码。 + +```go +type clientInfo struct { + Registered *bool `json:"registered"` // 目标服务器注册状态 + IsAutoUpdate *bool `json:"isautoupdate"`// 目标服务器基准值更新策略 +} +``` + +```shell +# curl -X POST -H "Authorization: $AUTHTOKEN" -H "Content-Type: application/json" http://localhost:40002/1 -d '{"registered":false, "isautoupdate":false}' +``` + +*** +若需要删除目标服务器，可以使用`"/{id}"`接口的`DELETE`方法。 +**注意：** +>使用该方法并非删除目标服务器的所有信息，而是把目标服务器的注册状态置为`false`！ + +```shell +# curl -X DELETE -H "Authorization: $AUTHTOKEN" -H "Content-Type: application/json" http://localhost:40002/1 +``` + +*** +若需要查询指定范围内的所有服务器信息，可以使用`"/{from}/{to}"`接口的`GET`方法。 + +```shell +# curl -X GET -H "Content-Type: application/json" http://localhost:40002/1/9 +``` + +*** +若需要查询目标服务器的所有可信报告，可以使用`"/{id}/reports"`接口的`GET`方法。 + +```shell +# curl -X GET -H "Content-Type: application/json" http://localhost:40002/1/reports +``` + +*** +若需要查询目标服务器指定可信报告的详细信息，可以使用`"/{id}/reports/{reportid}"`接口的`GET`方法，其中{reportid}是RAS为目标服务器指定可信报告分配的唯一标识号。 + +```shell +# curl -X GET -H "Content-Type: application/json" http://localhost:40002/1/reports/1 +``` + +*** +若需要删除目标服务器指定可信报告，可以使用`"/{id}/reports/{reportid}"`接口的`DELETE`方法。 +**注意：** +>使用该方法将删除指定可信报告的所有信息，将无法再通过接口对该报告进行查询！ + +```shell +# curl -X DELETE -H "Authorization: $AUTHTOKEN" -H "Content-Type: application/json" http://localhost:40002/1/reports/1 +``` + +*** +若需要查询目标服务器的所有基准值，可以使用`"/{id}/basevalues"`接口的`GET`方法。 + +```shell +# curl -X GET -H "Content-Type: application/json" http://localhost:40002/1/basevalues +``` + +*** +若需要给目标服务器新增一条基准值信息，可以使用`"/{id}/newbasevalue"`接口的`POST`方法。 + +```go +type baseValueJson struct { + BaseType string `json:"basetype"` // 基准值类型 + Uuid string `json:"uuid"` // 容器或设备的标识号 + Name string `json:"name"` // 基准值名称 + Enabled bool `json:"enabled"` // 基准值是否可用 + Pcr string `json:"pcr"` // PCR值 + Bios string `json:"bios"` // BIOS值 + Ima string `json:"ima"` // IMA值 + IsNewGroup bool `json:"isnewgroup"` // 是否为一组新的基准值 +} +``` + +```shell +# curl -X POST -H "Authorization: $AUTHTOKEN" -H "Content-Type: application/json" http://localhost:40002/1/newbasevalue -d '{"name":"test", "basetype":"host", "enabled":true, "pcr":"testpcr", "bios":"testbios", "ima":"testima", "isnewgroup":true}' +``` + +*** +若需要查询目标服务器指定基准值的详细信息，可以使用`"/{id}/basevalues/{basevalueid}"`接口的`GET`方法，其中{basevalueid}是RAS为目标服务器指定基准值分配的唯一标识号。 + +```shell +# curl -X GET -H "Content-Type: application/json" http://localhost:40002/1/basevalues/1 +``` + +*** +若需要修改目标服务器指定基准值的可用状态，可以使用`"/{id}/basevalues/{basevalueid}"`接口的`POST`方法。 + +```shell +# curl -X POST -H "Content-type: application/json" -H "Authorization: $AUTHTOKEN" http://localhost:40002/1/basevalues/1 -d '{"enabled":true}' +``` + +*** +若需要删除目标服务器指定基准值，可以使用`"/{id}/basevalues/{basevalueid}"`接口的`DELETE`方法。 +**注意：** +>使用该方法将删除指定基准值的所有信息，将无法再通过接口对该基准值进行查询！ + +```shell +# curl -X DELETE -H "Authorization: $AUTHTOKEN" -H "Content-Type: application/json" http://localhost:40002/1/basevalues/1 +``` + +*** +若需要查询目标服务器上特定用户 TA 的可信状态，可以使用`"/{id}/ta/{tauuid}/status"`接口的GET方法。其中{id}是RAS为目标服务器分配的唯一标识号，{tauuid}是特定用户 TA 的身份标识号。 + +```shell +# curl -X GET -H "Content-type: application/json" -H "Authorization: $AUTHTOKEN" http://localhost:40002/1/ta/test/status +``` + +*** +若需要查询目标服务器上特定用户 TA 的所有基准值信息，可以使用`"/{id}/ta/{tauuid}/tabasevalues"`接口的GET方法。 + +```shell +# curl -X GET -H "Content-type: application/json" http://localhost:40002/1/ta/test/tabasevalues +``` + +*** +若需要查询目标服务器上特定用户 TA 的指定基准值的详细信息，可以使用`"/{id}/ta/{tauuid}/tabasevalues/{tabasevalueid}"`接口的GET方法。其中{tabasevalueid}是RAS为目标服务器上特定用户 TA 的指定基准值分配的唯一标识号。 + +```shell +# curl -X GET -H "Content-type: application/json" http://localhost:40002/1/ta/test/tabasevalues/1 +``` + +*** +若需要修改目标服务器上特定用户 TA 的指定基准值的可用状态，可以使用`"/{id}/ta/{tauuid}/tabasevalues/{tabasevalueid}"`接口的`POST`方法。 + +```shell +# curl -X POST -H "Content-type: application/json" -H "Authorization: $AUTHTOKEN" http://localhost:40002/1/ta/test/tabasevalues/1 --data '{"enabled":true}' +``` + +*** +若需要删除目标服务器上特定用户 TA 的指定基准值，可以使用`"/{id}/ta/{tauuid}/tabasevalues/{tabasevalueid}"`接口的`DELETE`方法。 +**注意：** +>使用该方法将删除指定基准值的所有信息，将无法再通过接口对该基准值进行查询！ + +```shell +# curl -X DELETE -H "Content-type: application/json" -H "Authorization: $AUTHTOKEN" -k http://localhost:40002/1/ta/test/tabasevalues/1 +``` + +*** +若需要给目标服务器上特定用户 TA 新增一条基准值信息，可以使用`"/{id}/ta/{tauuid}/newtabasevalue"`接口的`POST`方法。 + +```go +type tabaseValueJson struct { + Uuid string `json:"uuid"` // 用户 TA 的标识号 + Name string `json:"name"` // 基准值名称 + Enabled bool `json:"enabled"` // 基准值是否可用 + Valueinfo string `json:"valueinfo"` // 镜像哈希值和内存哈希值 +} +``` + +```shell +# curl -X POST -H "Content-Type: application/json" -H "Authorization: $AUTHTOKEN" -k http://localhost:40002/1/ta/test/newtabasevalue -d '{"uuid":"test", "name":"testname", "enabled":true, "valueinfo":"test info"}' +``` + +*** +若需要查询目标服务器上特定用户 TA 的所有可信报告，可以使用`"/{id}/ta/{tauuid}/tareports"`接口的`GET`方法。 + +```shell +# curl -X GET -H "Content-type: application/json" http://localhost:40002/1/ta/test/tareports +``` + +*** +若需要查询目标服务器上特定用户 TA 的指定可信报告的详细信息，可以使用`"/{id}/ta/{tauuid}/tareports/{tareportid}"`接口的`GET`方法，其中{tareportid}是RAS为目标服务器上特定用户 TA 的指定可信报告分配的唯一标识号。 + +```shell +# curl -X GET -H "Content-type: application/json" http://localhost:40002/1/ta/test/tareports/2 +``` + +*** +若需要删除目标服务器上特定用户 TA 的指定可信报告，可以使用`"/{id}/ta/{tauuid}/tareports/{tareportid}"`接口的`DELETE`方法。 +**注意：** +>使用该方法将删除指定可信报告的所有信息，将无法再通过接口对该报告进行查询！ + +```shell +# curl -X DELETE -H "Content-type: application/json" http://localhost:40002/1/ta/test/tareports/2 +``` + +*** +若需要获取本程序的版本信息，可以使用`"/version"`接口的`GET`方法。 + +```shell +# curl -X GET -H "Content-Type: application/json" http://localhost:40002/version +``` + +*** +若需要查询目标服务器/RAS/数据库的配置信息，可以使用`"/config"`接口的`GET`方法。 + +```shell +# curl -X GET -H "Content-Type: application/json" http://localhost:40002/config +``` + +*** +若需要修改目标服务器/RAS/数据库的配置信息，可以使用`"/config"`接口的`POST`方法。 + +```go +type cfgRecord struct { + // 目标服务器配置 + HBDuration string `json:"hbduration" form:"hbduration"` + TrustDuration string `json:"trustduration" form:"trustduration"` + DigestAlgorithm string `json:"digestalgorithm" form:"digestalgorithm"` + // RAS配置 + MgrStrategy string `json:"mgrstrategy" form:"mgrstrategy"` + ExtractRules string `json:"extractrules" form:"extractrules"` + IsAllupdate *bool `json:"isallupdate" form:"isallupdate"` + LogTestMode *bool `json:"logtestmode" form:"logtestmode"` +} +``` + +```shell +# curl -X POST -H "Authorization: $AUTHTOKEN" -H "Content-Type: application/json" http://localhost:40002/config -d '{"hbduration":"5s","trustduration":"20s","DigestAlgorithm":"sha256"}' +``` + +### TAS接口 + +为了便于管理员对TAS服务的远程控制，本程序设计了以下接口可供调用： + +| 接口 | 方法 | +| --------------------| ------------------| +| /config | GET、POST | + +若需要查询TAS的配置信息，可使用`"/config"`接口的`GET`方法： + +```shell +# curl -X GET -H "Content-Type: application/json" http://localhost:40009/config +``` + +*** +若需要修改TAS的配置信息，可使用`"/config"`接口的`POST`方法： + +```shell +curl -X POST -H "Content-Type: application/json" -H "Authorization: $AUTHTOKEN" http://localhost:40009/config -d '{"basevalue":"testvalue"}' +``` + +**注意：** +>TAS的配置信息读取与修改目前仅支持基准值 diff --git a/docs/zh/docs/ApplicationDev/FAQ.md b/docs/zh/docs/ApplicationDev/FAQ.md deleted file mode 100644 index b997844d819dd62509e039d9483c4305053927ee..0000000000000000000000000000000000000000 --- a/docs/zh/docs/ApplicationDev/FAQ.md +++ /dev/null @@ -1,19 +0,0 @@ -# FAQ - -## 部分依赖java-devel的应用程序自编译失败 - -### 问题描述 - -部分依赖java-devel的应用程序会出现使用rpmbuild命令自编译失败的问题。 - -### 原因分析 - -为了提供更新的openjdk特性和对广大java应用程序的兼容，openEuler同时提供了openjdk-1.8.0、openjdk-11等多个版本的openjdk。部分应用程序在编译时需要依赖java-devel包，安装java-devel包时系统会默认安装更高版本的java-11-openjdk，从而导致这些应用的编译失败。 - -### 解决方法 - -用户需手动使用如下命令安装java-1.8.0-openjdk后再使用rpmbuild命令进行自编译。 - -```shell -# yum install java-1.8.0-openjdk -``` diff --git "a/docs/zh/docs/ApplicationDev/\344\275\277\347\224\250Clang\347\274\226\350\257\221.md" "b/docs/zh/docs/ApplicationDev/\344\275\277\347\224\250Clang\347\274\226\350\257\221.md" index 2d25fd54df82d76231dd303bae176647b60968fb..4549e1759fa3196712ef58b6fcbacf76e0585c70 100644 --- "a/docs/zh/docs/ApplicationDev/\344\275\277\347\224\250Clang\347\274\226\350\257\221.md" +++ "b/docs/zh/docs/ApplicationDev/\344\275\277\347\224\250Clang\347\274\226\350\257\221.md" @@ -1,103 +1,90 @@ # 使用LLVM/Clang编译 本章介绍LLVM/Clang编译的一些基本知识，并通过示例进行实际演示。更多Clang使用方法请通过**clang --help**命令查询。 + - [使用LLVM/Clang编译](#使用llvmclang编译) - [简介](#简介) - - [LLVM/Clang安装](#llvmclang安装) - - [多版本共存支持](#多版本共存支持) - - [示例](#示例) + - [LLVM/Clang多版本安装](#LLVMClang多版本安装) + - [使用示例](#使用示例) + - [手动构建支持](#手动构建支持) ## 简介 -LLVM是一种涵盖多种编程语言和目标处理器的编译器，使用Clang作为C和C++的编译和驱动程序。Clang不仅仅可以将C, C++程序编译为LLVM中间表示的IR，也会调用所有以代码生成为目标的LLVM优化遍，直到生成最终的二进制文件。 +LLVM是一种涵盖多种编程语言和目标处理器的编译器，使用Clang作为C和C++的编译和驱动程序。Clang不仅仅可以将C/C++程序编译为LLVM中间表示的IR，也会调用所有以代码生成为目标的LLVM优化遍，直到生成最终的二进制文件。 -## LLVM/Clang安装 +## LLVM/Clang多版本安装 -openEuler操作系统中通过yum源安装Clang和LLVM软件包。默认安装llvm-12 +在openEuler操作系统中，Clang/LLVM工具链可通过官方yum仓库进行标准化安装。为兼容不同场景对LLVM版本的需求，系统采用主副版本共存机制：默认安装稳定主版本的同时，支持部署更高版本的LLVM。 -```shell -yum install llvm -yum install clang -yum install lld // openEuler yum源中目前没有lld-12版本 -``` +| openEuler版本 | LLVM主版本 | 安装方式 | LLVM副版本 | 安装方式 | +|----------------|------------|--------------------------|---------------|--------------------------------------------------------------------------| +| 22.03 LTS SP3 | LLVM12 | yum install -y clang | LLVM17、LLVM18 | yum install -y llvm-toolset-17
yum install -y llvm-toolset-18| +| 22.03 LTS SP4 | LLVM12 | yum install -y clang | LLVM17、LLVM18 | yum install -y llvm-toolset-17
yum install -y llvm-toolset-18| +| 24.03 LTS | LLVM17 | yum install -y clang | NA | NA | +| 24.03 LTS SP1 | LLVM17 | yum install -y clang | LLVM18 | yum install -y llvm-toolset-18| -验证安装是否成功 +以openEuler 22.03 LTS SP4为例，验证主版本安装是否成功： ```shell clang -v -``` - -若返回结果中包含clang版本信息，说明安装成功。 - -## 多版本共存支持 - -openEuler LLVM/Clang 多版本支持的方式如下： - -```text -yum包名： -llvm
+ 软件包下载地址：[https://repo.openeuler.org/openEuler-22.03-LTS-SP4/ ](https://repo.openeuler.org/openEuler-22.03-LTS-SP4/) + 镜像下载地址：[https://developer.aliyun.com/mirror/](https://developer.aliyun.com/mirror/) + +## 修改host文件 + +1. 修改主机名，以其中一台机器为例。 + + ```shell + # hostnamectl set-hostname lab1 + # sudo -i + ``` + +2. 配置主机名解析，编辑三台服务器的/etc/hosts文件。 + + ```shell + # vim /etc/hosts + ``` + +3. 在hosts文件中添加以下内容（IP+主机名）。 + + ```text + 197.xxx.xxx.xxx lab1 + 197.xxx.xxx.xxx lab2 + 197.xxx.xxx.xxx lab3 + ``` + +## 环境准备 + +1. 关闭防火墙。 + + ```shell + # systemctl stop firewalld + # systemctl disable firewalld + ``` + +2. 禁用selinux。 + + ```shell + # setenforce 0 + ``` + +3. 关闭系统swap。 + + ```shell + # swapoff -a + # sed -ri 's/.*swap.*/#&/' /etc/fstab + ``` + +4. 网络配置，开启相应的转发机制。 + + ```shell + # cat > /etc/sysctl.d/kubernetes.conf <
| + | ++ | +
|---|---|
| + | ++ | +
| + | ++ | +
| + | ++ | +
|---|---|
| + | ++ | +
| + | ++ | +
|---|---|
| + | ++ | +
| + | ++ | +
| + | ++ | +
| + | ++ | +
| + | ++ | +
|---|---|
| + | ++ | +
| + | ++ | +
| + | ++ | +
| + | ++ | +
| + | ++ | +
| + | ++ | +
| + | ++ | +
| + | ++ | +
| + | ++ | +
| + | ++ | +
| + | ++ | +
false：关闭debug日志 | +| loglevel | 可选 | 设置日志级别 | debug
info
warn
error | +| run_root | 必选 | 设置运行时数据根目录 | 运行时数据根目录路径，例如/var/run/isula-build/ | +| data_root | 必选 | 设置本地持久化目录 | 本地持久化目录路径，例如/var/lib/isula-build/ | +| runtime | 可选 | 设置runtime种类，目前仅支持runc | runc | +| group | 可选 | 设置本地套接字isula_build.sock文件属组使得加入该组的非特权用户可以操作isula-build | isula | +| experimental | 可选 | 设置是否开启实验特性 | true：开启实验特性；false：关闭实验特性 | + +* /etc/isula-build/storage.toml: 本地持久化存储的配置文件，包含所使用的存储驱动的配置。 + +| 配置项 | 是否可选 | 配置项含义 | +| ------ | -------- | ------------------------------ | +| driver | 可选 | 存储驱动类型，目前支持overlay2 | + + 更多设置可参考 [containers-storage.conf.5](https://github.com/containers/storage/blob/main/docs/containers-storage.conf.5.md)。 + +* /etc/isula-build/registries.toml : 针对各个镜像仓库的配置文件。 + +| 配置项 | 是否可选 | 配置项含义 | +| ------------------- | -------- | ------------------------------------------------------------ | +| registries.search | 可选 | 镜像仓库搜索域，在此list的镜像仓库可以被感知，不在此列的不被感知。 | +| registries.insecure | 可选 | 可访问的不安全镜像仓库地址，在此列表中的镜像仓库将不会通过鉴权，不推荐使用。 | + + 更多设置可参考 [containers-registries.conf.5](https://github.com/containers/image/blob/main/docs/containers-registries.conf.5.md)。 + +* /etc/isula-build/policy.json：镜像pull/push策略文件。当前不支持对其进行配置。 + +>  **说明：** +> +> * isula-build 支持最大 1MiB 的上述配置文件。 +> * isula-build 不支持将持久化工作目录 dataroot 配置在内存盘上，比如 tmpfs。 +> * isula-build 目前仅支持使用overlay2为底层 graphdriver。 +> * 在设置--group参数前，需保证本地OS已经创建了对应的用户组，且非特权用户已经加入该组。重启isula-builder之后即可使该非特权用户使用isula-build功能。同时，为了保持权限一致性，isula-build的配置文件目录/etc/isula-build的属组也会被设置为--group指定的组。 + +## 管理服务 + +目前 openEuler 采用 systemd 管理软件服务，isula-build 软件包已经自带了 systemd 的服务文件，用户安装完 isula-build 软件包之后，可以直接通过 systemd 工具对它进行服务启停等操作。用户同样可以手动启动 isula-build 服务端软件。需要注意的是，同一个节点上不可以同时启动多个 isula-build 服务端软件。 + +> **说明：** +> +> 同一个节点上不可以同时启动多个 isula-build 服务端软件。 + +### 通过 systemd 管理（推荐方式） + +用户可以通过如下 systemd 的标准指令控制 isula-build 服务的启动、停止、重启等动作： + +* 启动 isula-build 服务： + + ```sh + sudo systemctl start isula-build.service + ``` + +* 停止 isula-build 服务： + + ```sh + sudo systemctl stop isula-build.service + ``` + +* 重启 isula-build 服务： + + ```sh + sudo systemctl restart isula-build.service + ``` + +isula-build 软件包安装的 systemd 服务文件保存在 `/usr/lib/systemd/system/isula-build.service`。如果用户需要修改 isula-build 服务的 systemd 配置，可以修改该文件，执行如下命令使配置生效，之后再根据上面提到的 systemd 管理指令重启 isula-build 服务 + +```sh +sudo systemctl daemon-reload +``` + +### 直接运行 isula-build 服务端 + +您也可以通过执行 isula-build 服务端命令（ isula-builder）的方式启动服务。其中，服务端启动配置，可通过isula-builder命令支持的 flags 设置。isula-build 服务端目前支持的 flags 如下： + +* -D, --debug: 是否开启调测模式。 +* --log-level: 日志级别，支持 “debug”, “info”, “warn” or “error”，默认为 “info”。 +* --dataroot: 本地持久化路径，默认为”/var/lib/isula-build/“。 +* --runroot: 运行时路径，默认为”/var/run/isula-build/“。 +* --storage-driver：底层存储驱动类型。 +* --storage-opt: 底层存储驱动配置。 +* --group: 设置本地套接字isula_build.sock文件属组使得加入该组的非特权用户可以操作isula-build，默认为“isula”。 +* --experimental: 是否开启实验特性，默认为false。 + +> **说明：** +> +> 当命令行启动参数中传递了与配置文件相同的配置选项时，优先使用命令行参数启动。 + +启动 isula-build 服务。例如指定本地持久化路径/var/lib/isula-build，且不开启调试的参考命令如下： + +```sh +sudo isula-builder --dataroot "/var/lib/isula-build" --debug=false +``` + +# 使用指南 + +## 前提条件 + +isula-build 构建 Dockerfile 内的 RUN 指令时依赖可执行文件 runc ，需要 isula-build 的运行环境上预装好 runc。安装方式视用户使用场景而定，如果用户不需要使用完整的 docker-engine 工具链，则可以仅安装 docker-runc rpm包： + +```sh +sudo yum install -y docker-runc +``` + +如果用户需要使用完整的 docker-engine 工具链，则可以安装 docker-engine rpm包，默认包含可执行文件 runc ： + +```sh +sudo yum install -y docker-engine +``` + +> **说明：** +> +> 用户需保证OCI runtime（runc）可执行文件的安全性，避免被恶意替换。 + +## 总体说明 + +isula-build 客户端提供了一系列命令用于构建和管理容器镜像，当前 isula-build 包含的命令行指令如下： + +* ctr-img，容器镜像管理。ctr-img又包含如下子命令： + * build，根据给定dockerfile构建出容器镜像。 + * images，列出本地容器镜像。 + * import，导入容器基础镜像。 + * load，导入层叠镜像。 + * rm，删除本地容器镜像。 + * save，导出层叠镜像至本地磁盘。 + * tag，给本地容器镜像打tag。 + * pull，拉取镜像到本地。 + * push，推送本地镜像到远程仓库。 +* info，查看isula-build的运行环境和系统信息。 +* login，登录远端容器镜像仓库。 +* logout，退出远端容器镜像仓库。 +* version，查看isula-build和isula-builder的版本号。 +* manifest（实验特性），管理manifest列表。 + +> **说明：** +> +> * isula-build completion 和 isula-builder completion 命令用于生成bash命令补全脚本。该命令为命令行框架隐式提供，不会显示在help信息中。 +> * isula-build客户端不包含配置文件，当用户需要使用isula-build实验特性时，需要在客户端通过命令`export ISULABUILD_CLI_EXPERIMENTAL=enabled`配置环境变量ISULABUILD_CLI_EXPERIMENTAL来开启实验特性。 + +以下按照上述维度依次详细介绍这些命令行指令的使用。 + +## ctr-img: 容器镜像管理 + +isula-build 将所有容器镜像管理相关命令划分在子命令 `ctr-img` 下，命令原型为： + +```sh +isula-build ctr-img [command] +``` + +### build: 容器镜像构建 + +ctr-img 的子命令 build 用于构建容器镜像，命令原型为： + +```sh +isula-build ctr-img build [flags] +``` + +其中 build 包含如下 flags： + +* --build-arg：string列表，构建过程中需要用到的变量。 +* --build-static：KeyValue值，构建二进制一致性。目前包含如下Key值： + * build-time：string，使用固定时间戳来构建容器镜像；时间戳格式为“YYYY-MM-DD HH-MM-SS”。 +* -f, --filename：string，Dockerfile的路径，不指定则是使用当前路径的Dockerfile文件。 +* --format： string, 设置构建镜像的镜像格式：oci | docker（需开启实验特性选项）。 +* --iidfile：string，输出 image ID 到本地文件。 +* -o, --output：string，镜像导出的方式和路径。 +* --proxy：布尔值，继承主机侧环境的proxy环境变量（默认为true）。 +* --tag：string，设置构建成功的镜像的tag值。 +* --cap-add：string列表，构建过程中RUN指令所需要的权限。 + +**以下为各个 flags 的详解。** + +**\--build-arg** + +从命令行接受参数作为Dockerfile中的参数，用法： + +```sh +$ echo "This is bar file" > bar.txt +$ cat Dockerfile_arg +FROM busybox +ARG foo +ADD ${foo}.txt . +RUN cat ${foo}.txt +$ sudo isula-build ctr-img build --build-arg foo=bar -f Dockerfile_arg +STEP 1: FROM busybox +Getting image source signatures +Copying blob sha256:8f52abd3da461b2c0c11fda7a1b53413f1a92320eb96525ddf92c0b5cde781ad +Copying config sha256:e4db68de4ff27c2adfea0c54bbb73a61a42f5b667c326de4d7d5b19ab71c6a3b +Writing manifest to image destination +Storing signatures +STEP 2: ARG foo +STEP 3: ADD ${foo}.txt . +STEP 4: RUN cat ${foo}.txt +This is bar file +Getting image source signatures +Copying blob sha256:6194458b07fcf01f1483d96cd6c34302ffff7f382bb151a6d023c4e80ba3050a +Copying blob sha256:6bb56e4a46f563b20542171b998cb4556af4745efc9516820eabee7a08b7b869 +Copying config sha256:39b62a3342eed40b41a1bcd9cd455d77466550dfa0f0109af7a708c3e895f9a2 +Writing manifest to image destination +Storing signatures +Build success with image id: 39b62a3342eed40b41a1bcd9cd455d77466550dfa0f0109af7a708c3e895f9a2 +``` + +**\--build-static** + +指定为静态构建，即使用isula-build构建容器镜像时消除所有时间戳和其他构建因素（例如容器ID、hostname等）的差异。最终构建出满足静态要求的容器镜像。 + +在使用isula-build进行容器镜像构建时，假如给 build 子命令一个固定的时间戳，并在限定如下条件的时候： + +* 构建环境前后保持一致。 +* 构建Dockerfile前后保持一致。 +* 构建产生的中间数据前后保持一致。 +* 构建命令相同。 +* 第三方库版本一致。 + +对于容器镜像构建，isula-build支持相同的Dockerfile。如果构建环境相同，则多次构建生成的镜像内容和镜像ID相同。 + +--build-static接受k=v形式的键值对选项，当前支持的选项有： + +* build-time：字符串类型。构建静态镜像的固定时间戳，格式为“YYYY-MM-DD HH-MM-SS”。时间戳影响diff层创建修改时间的文件属性。 + + 使用示例如下： + + ```sh + sudo isula-build ctr-img build -f Dockerfile --build-static='build-time=2020-05-23 10:55:33' . + ``` + + 以此方式，同一环境多次构建出来的容器镜像和镜像ID均会保持一致。 + +**\--format** +开始实验特性后该选项可用，默认为OCI镜像格式。可以手动指定镜像格式进行构建，例如，下面分别为构建OCI镜像格式以及Docker镜像格式镜像的命令。 + + ```sh + export ISULABUILD_CLI_EXPERIMENTAL=enabled; sudo isula-build ctr-img build -f Dockerfile --format oci . + ``` + + ```sh + export ISULABUILD_CLI_EXPERIMENTAL=enabled; sudo isula-build ctr-img build -f Dockerfile --format docker . + ``` + +**\--iidfile** + +将构建的镜像ID输出到文件，用法： + +```sh +isula-build ctr-img build --iidfile filename +``` + +例如，将容器镜像ID输出到testfile的参考命令如下： + + ```sh +sudo isula-build ctr-img build -f Dockerfile_arg --iidfile testfile + ``` + + 查看testfile中的容器镜像ID： + + ```sh +$ cat testfile +76cbeed38a8e716e22b68988a76410eaf83327963c3b29ff648296d5cd15ce7b + ``` + +**\-o, --output** + +目前 -o, --output 支持如下形式： + +* `isulad:image:tag`：将构建成功的镜像直接推送到 iSulad。比如：`-o isulad:busybox:latest`。同时需要注意如下约束： + + * isula-build 和 iSulad 必须在同一个节点上 + * tag必须配置 + * isula-build client端需要将构建成功的镜像暂存成 `/var/tmp/isula-build-tmp-%v.tar` 再导入至 iSulad，用户需要保证 `/var/tmp/` 目录有足够磁盘空间 + +* `docker-daemon:image:tag`：将构建成功的镜像直接推送到 Docker daemon。比如：`-o docker-daemon:busybox:latest`。同时需要注意如下约束： + * isula-build 和 docker 必须在同一个节点上 + * tag必须配置 + +* `docker://registry.example.com/repository:tag`：将构建成功的镜像以Docker镜像格式直接推送到远端镜像仓库。比如：`-o docker://localhost:5000/library/busybox:latest`。 + +* `docker-archive:
false：关闭debug日志 | -| loglevel | 可选 | 设置日志级别 | debug
info
warn
error | -| run_root | 必选 | 设置运行时数据根目录 | 运行时数据根目录路径，例如/var/run/isula-build/ | -| data_root | 必选 | 设置本地持久化目录 | 本地持久化目录路径，例如/var/lib/isula-build/ | -| runtime | 可选 | 设置runtime种类，目前仅支持runc | runc | -| group | 可选 | 设置本地套接字isula_build.sock文件属组使得加入该组的非特权用户可以操作isula-build | isula | -| experimental | 可选 | 设置是否开启实验特性 | true：开启实验特性；false：关闭实验特性 | - -* /etc/isula-build/storage.toml: 本地持久化存储的配置文件，包含所使用的存储驱动的配置。 - -| 配置项 | 是否可选 | 配置项含义 | -| ------ | -------- | ------------------------------ | -| driver | 可选 | 存储驱动类型，目前支持overlay2 | - - 更多设置可参考 [containers-storage.conf.5](https://github.com/containers/storage/blob/main/docs/containers-storage.conf.5.md)。 - -* /etc/isula-build/registries.toml : 针对各个镜像仓库的配置文件。 - -| 配置项 | 是否可选 | 配置项含义 | -| ------------------- | -------- | ------------------------------------------------------------ | -| registries.search | 可选 | 镜像仓库搜索域，在此list的镜像仓库可以被感知，不在此列的不被感知。 | -| registries.insecure | 可选 | 可访问的不安全镜像仓库地址，在此列表中的镜像仓库将不会通过鉴权，不推荐使用。 | - - 更多设置可参考 [containers-registries.conf.5](https://github.com/containers/image/blob/main/docs/containers-registries.conf.5.md)。 - -* /etc/isula-build/policy.json：镜像pull/push策略文件。当前不支持对其进行配置。 - ->  **说明：** -> -> * isula-build 支持最大 1MiB 的上述配置文件。 -> * isula-build 不支持将持久化工作目录 dataroot 配置在内存盘上，比如 tmpfs。 -> * isula-build 目前仅支持使用overlay2为底层 graphdriver。 -> * 在设置--group参数前，需保证本地OS已经创建了对应的用户组，且非特权用户已经加入该组。重启isula-builder之后即可使该非特权用户使用isula-build功能。同时，为了保持权限一致性，isula-build的配置文件目录/etc/isula-build的属组也会被设置为--group指定的组。 - -### 管理服务 - -目前 openEuler 采用 systemd 管理软件服务，isula-build 软件包已经自带了 systemd 的服务文件，用户安装完 isula-build 软件包之后，可以直接通过 systemd 工具对它进行服务启停等操作。用户同样可以手动启动 isula-build 服务端软件。需要注意的是，同一个节点上不可以同时启动多个 isula-build 服务端软件。 - -> **说明：** -> -> 同一个节点上不可以同时启动多个 isula-build 服务端软件。 - -#### 通过 systemd 管理（推荐方式） - -用户可以通过如下 systemd 的标准指令控制 isula-build 服务的启动、停止、重启等动作： - -* 启动 isula-build 服务： - - ```sh - sudo systemctl start isula-build.service - ``` - -* 停止 isula-build 服务： - - ```sh - sudo systemctl stop isula-build.service - ``` - -* 重启 isula-build 服务： - - ```sh - sudo systemctl restart isula-build.service - ``` - -isula-build 软件包安装的 systemd 服务文件保存在 `/usr/lib/systemd/system/isula-build.service`。如果用户需要修改 isula-build 服务的 systemd 配置，可以修改该文件，执行如下命令使配置生效，之后再根据上面提到的 systemd 管理指令重启 isula-build 服务 - -```sh -sudo systemctl daemon-reload -``` - -#### 直接运行 isula-build 服务端 - -您也可以通过执行 isula-build 服务端命令（ isula-builder）的方式启动服务。其中，服务端启动配置，可通过isula-builder命令支持的 flags 设置。isula-build 服务端目前支持的 flags 如下： - -* -D, --debug: 是否开启调测模式。 -* --log-level: 日志级别，支持 “debug”, “info”, “warn” or “error”，默认为 “info”。 -* --dataroot: 本地持久化路径，默认为”/var/lib/isula-build/“。 -* --runroot: 运行时路径，默认为”/var/run/isula-build/“。 -* --storage-driver：底层存储驱动类型。 -* --storage-opt: 底层存储驱动配置。 -* --group: 设置本地套接字isula_build.sock文件属组使得加入该组的非特权用户可以操作isula-build，默认为“isula”。 -* --experimental: 是否开启实验特性，默认为false。 - -> **说明：** -> -> 当命令行启动参数中传递了与配置文件相同的配置选项时，优先使用命令行参数启动。 - -启动 isula-build 服务。例如指定本地持久化路径/var/lib/isula-build，且不开启调试的参考命令如下： - -```sh -sudo isula-builder --dataroot "/var/lib/isula-build" --debug=false -``` - -## 使用指南 - -### 前提条件 - -isula-build 构建 Dockerfile 内的 RUN 指令时依赖可执行文件 runc ，需要 isula-build 的运行环境上预装好 runc。安装方式视用户使用场景而定，如果用户不需要使用完整的 docker-engine 工具链，则可以仅安装 docker-runc rpm包： - -```sh -sudo yum install -y docker-runc -``` - -如果用户需要使用完整的 docker-engine 工具链，则可以安装 docker-engine rpm包，默认包含可执行文件 runc ： - -```sh -sudo yum install -y docker-engine -``` - -> **说明：** -> -> 用户需保证OCI runtime（runc）可执行文件的安全性，避免被恶意替换。 - -### 总体说明 - -isula-build 客户端提供了一系列命令用于构建和管理容器镜像，当前 isula-build 包含的命令行指令如下： - -* ctr-img，容器镜像管理。ctr-img又包含如下子命令： - * build，根据给定dockerfile构建出容器镜像。 - * images，列出本地容器镜像。 - * import，导入容器基础镜像。 - * load，导入层叠镜像。 - * rm，删除本地容器镜像。 - * save，导出层叠镜像至本地磁盘。 - * tag，给本地容器镜像打tag。 - * pull，拉取镜像到本地。 - * push，推送本地镜像到远程仓库。 -* info，查看isula-build的运行环境和系统信息。 -* login，登录远端容器镜像仓库。 -* logout，退出远端容器镜像仓库。 -* version，查看isula-build和isula-builder的版本号。 -* manifest（实验特性），管理manifest列表。 - -> **说明：** -> -> * isula-build completion 和 isula-builder completion 命令用于生成bash命令补全脚本。该命令为命令行框架隐式提供，不会显示在help信息中。 -> * isula-build客户端不包含配置文件，当用户需要使用isula-build实验特性时，需要在客户端通过命令`export ISULABUILD_CLI_EXPERIMENTAL=enabled`配置环境变量ISULABUILD_CLI_EXPERIMENTAL来开启实验特性。 - -以下按照上述维度依次详细介绍这些命令行指令的使用。 - -### ctr-img: 容器镜像管理 - -isula-build 将所有容器镜像管理相关命令划分在子命令 `ctr-img` 下，命令原型为： - -```sh -isula-build ctr-img [command] -``` - -#### build: 容器镜像构建 - -ctr-img 的子命令 build 用于构建容器镜像，命令原型为： - -```sh -isula-build ctr-img build [flags] -``` - -其中 build 包含如下 flags： - -* --build-arg：string列表，构建过程中需要用到的变量。 -* --build-static：KeyValue值，构建二进制一致性。目前包含如下Key值： - * build-time：string，使用固定时间戳来构建容器镜像；时间戳格式为“YYYY-MM-DD HH-MM-SS”。 -* -f, --filename：string，Dockerfile的路径，不指定则是使用当前路径的Dockerfile文件。 -* --format： string, 设置构建镜像的镜像格式：oci | docker（需开启实验特性选项）。 -* --iidfile：string，输出 image ID 到本地文件。 -* -o, --output：string，镜像导出的方式和路径。 -* --proxy：布尔值，继承主机侧环境的proxy环境变量（默认为true）。 -* --tag：string，设置构建成功的镜像的tag值。 -* --cap-add：string列表，构建过程中RUN指令所需要的权限。 - -**以下为各个 flags 的详解。** - -**\--build-arg** - -从命令行接受参数作为Dockerfile中的参数，用法： - -```sh -$ echo "This is bar file" > bar.txt -$ cat Dockerfile_arg -FROM busybox -ARG foo -ADD ${foo}.txt . -RUN cat ${foo}.txt -$ sudo isula-build ctr-img build --build-arg foo=bar -f Dockerfile_arg -STEP 1: FROM busybox -Getting image source signatures -Copying blob sha256:8f52abd3da461b2c0c11fda7a1b53413f1a92320eb96525ddf92c0b5cde781ad -Copying config sha256:e4db68de4ff27c2adfea0c54bbb73a61a42f5b667c326de4d7d5b19ab71c6a3b -Writing manifest to image destination -Storing signatures -STEP 2: ARG foo -STEP 3: ADD ${foo}.txt . -STEP 4: RUN cat ${foo}.txt -This is bar file -Getting image source signatures -Copying blob sha256:6194458b07fcf01f1483d96cd6c34302ffff7f382bb151a6d023c4e80ba3050a -Copying blob sha256:6bb56e4a46f563b20542171b998cb4556af4745efc9516820eabee7a08b7b869 -Copying config sha256:39b62a3342eed40b41a1bcd9cd455d77466550dfa0f0109af7a708c3e895f9a2 -Writing manifest to image destination -Storing signatures -Build success with image id: 39b62a3342eed40b41a1bcd9cd455d77466550dfa0f0109af7a708c3e895f9a2 -``` - -**\--build-static** - -指定为静态构建，即使用isula-build构建容器镜像时消除所有时间戳和其他构建因素（例如容器ID、hostname等）的差异。最终构建出满足静态要求的容器镜像。 - -在使用isula-build进行容器镜像构建时，假如给 build 子命令一个固定的时间戳，并在限定如下条件的时候： - -* 构建环境前后保持一致。 -* 构建Dockerfile前后保持一致。 -* 构建产生的中间数据前后保持一致。 -* 构建命令相同。 -* 第三方库版本一致。 - -对于容器镜像构建，isula-build支持相同的Dockerfile。如果构建环境相同，则多次构建生成的镜像内容和镜像ID相同。 - ---build-static接受k=v形式的键值对选项，当前支持的选项有： - -* build-time：字符串类型。构建静态镜像的固定时间戳，格式为“YYYY-MM-DD HH-MM-SS”。时间戳影响diff层创建修改时间的文件属性。 - - 使用示例如下： - - ```sh - sudo isula-build ctr-img build -f Dockerfile --build-static='build-time=2020-05-23 10:55:33' . - ``` - - 以此方式，同一环境多次构建出来的容器镜像和镜像ID均会保持一致。 - -**\--format** -开始实验特性后该选项可用，默认为OCI镜像格式。可以手动指定镜像格式进行构建，例如，下面分别为构建OCI镜像格式以及Docker镜像格式镜像的命令。 - - ```sh - export ISULABUILD_CLI_EXPERIMENTAL=enabled; sudo isula-build ctr-img build -f Dockerfile --format oci . - ``` - - ```sh - export ISULABUILD_CLI_EXPERIMENTAL=enabled; sudo isula-build ctr-img build -f Dockerfile --format docker . - ``` - -**\--iidfile** - -将构建的镜像ID输出到文件，用法： - -```sh -isula-build ctr-img build --iidfile filename -``` - -例如，将容器镜像ID输出到testfile的参考命令如下： - - ```sh -sudo isula-build ctr-img build -f Dockerfile_arg --iidfile testfile - ``` - - 查看testfile中的容器镜像ID： - - ```sh -$ cat testfile -76cbeed38a8e716e22b68988a76410eaf83327963c3b29ff648296d5cd15ce7b - ``` - -**\-o, --output** - -目前 -o, --output 支持如下形式： - -* `isulad:image:tag`：将构建成功的镜像直接推送到 iSulad。比如：`-o isulad:busybox:latest`。同时需要注意如下约束： - - * isula-build 和 iSulad 必须在同一个节点上 - * tag必须配置 - * isula-build client端需要将构建成功的镜像暂存成 `/var/tmp/isula-build-tmp-%v.tar` 再导入至 iSulad，用户需要保证 `/var/tmp/` 目录有足够磁盘空间 - -* `docker-daemon:image:tag`：将构建成功的镜像直接推送到 Docker daemon。比如：`-o docker-daemon:busybox:latest`。同时需要注意如下约束： - * isula-build 和 docker 必须在同一个节点上 - * tag必须配置 - -* `docker://registry.example.com/repository:tag`：将构建成功的镜像以Docker镜像格式直接推送到远端镜像仓库。比如：`-o docker://localhost:5000/library/busybox:latest`。 - -* `docker-archive:
| @@ -648,7 +644,7 @@ isula run -ti --pids-limit 1024 busybox bash |
|---|
0表示插件enable后即持续低频采样
1表示enable时启动监控线程，只有负载达到阈值场景才采样
当前由oeaware控制采样流程，仅支持0 | +| COLLECTOR_HIGH_LOAD_THRESHOLD | `[0, cpus*100]` | 不可用 | 仅在采样策略1场景下生效，使用HIGH_LOAD_THRESHOLD作为触发采样的应用CPU使用率阈值，当前不支持 | +| COLLECTOR_DATA_AGING_TIME | 按实际需要确定 | 可用 | 采样数据老化时间，当前数据与最老数据时间差值达到阈值时，丢弃累积采样数据，单位ms | +| TUNER_TOOL | `["sysboost"]` | 不可用 | 二进制优化器，当前仅支持sysboost | +| TUNER_CHECK_PERIOD | `[10, max]` | 可用 | 优化插件检查时间间隔，每隔一段时间收集采样插件数据并决定是否进行优化，单位ms | +| TUNER_PROFILE_DIR | 按实际需要确定 | 可用 | 采样数据存放位置，profile文件被命名为`[app_name]_[full_path_hash]_[threshold].profile` | +| TUNER_OPTIMIZING_STRATEGY | `[0, 1]` | 可用 | 优化策略，0表示只优化一次，1表示只要采样信息在刷新，可以持续多次优化 | +| TUNER_OPTIMIZING_CONDITION | `[0, 2]` | 不可用 | 触发优化的条件，0表示应用退出后即开始优化，1表示低负载时优化，2表示应用退出且低负载时优化，当前仅支持0 | +应用配置： [app] + +| 配置项 | 值范围 | 是否可用 | 说明 | +| ----------------------------- | -------------- | ---- | ------------------------------------------------------------------------------------------ | +| FULL_PATH | 按实际需要确定 | 可用 | 应用二进制文件绝对路径 | +| DEFAULT_PROFILE | 按实际需要确定 | 可用 | 应用的开箱profile文件，用于冷启动时使能二进制优化，没有则留空 | +| COLLECTOR_DUMP_DATA_THRESHOLD | `[10000, max]` | 可用 | 采样数据达到该阈值行数时触发数据导出到profile，数值越大需要的采集的samples越多 | +| BOLT_DIR | NA | 不可用 | BOLT工具路径,留空则默认/usr/bin，内部会调用`${BOLT_DIR}/perf2bolt和${BOLT_DIR}/llvm-bolt`
当前由sysboost确定 | +| BOLT_OPTIONS | 按实际需要确定 | 可用 | BOLT优化选项，配置该项可以覆盖内置的默认选项，用于针对性的选项调优 | +| UPDATE_DEBUG_INFO | `[0, 1]` | 可用 | 优化时是否同步更新调试信息，1表示更新，0表示不更新，注意更新调试信息会有额外耗时 | + +### 插件使用 + +参考[oeAware-manager](https://gitee.com/openeuler/oeAware-manager/tree/master/docs) + +## 约束限制 + +1. 支持容器部署场景使用，D-FOT等优化组件需部署在容器外。 +2. 待优化的目标应用需要具备重定位信息。 +3. 作为oeAware调优插件使用D-FOT时，当前对应的oeAware采集插件pmu_sampling_collector固定采样频率为100，可能会导致采样时间较久（作为参考：perf默认采样频率为4000）。 + +## 未来规划 + +- [ ] 虚拟化场景完善 +- [ ] 运行时优化支持 +- [ ] 进一步提升二进制优化效果 diff --git "a/docs/zh/docs/GCC/\351\223\276\346\216\245\346\227\266\344\274\230\345\214\226\347\211\271\346\200\247\347\224\250\346\210\267\346\214\207\345\215\227.md" "b/docs/zh/docs/GCC/\351\223\276\346\216\245\346\227\266\344\274\230\345\214\226\347\211\271\346\200\247\347\224\250\346\210\267\346\214\207\345\215\227.md" new file mode 100644 index 0000000000000000000000000000000000000000..7744f40b490935345128ff93a972b0b5aa74cabd --- /dev/null +++ "b/docs/zh/docs/GCC/\351\223\276\346\216\245\346\227\266\344\274\230\345\214\226\347\211\271\346\200\247\347\224\250\346\210\267\346\214\207\345\215\227.md" @@ -0,0 +1,25 @@ +# 链接时优化简介 + +在传统编译流程中，gcc 将单个源文件（称谓一个编译单元）直接进行编译优化生成包含汇编代码的`.o`目标对象文件，并由链接器对这些`.o`文件进行符号表解析与重定位，链接成可执行文件。在这个过程中，拥有跨文件函数调用信息的链接器由于操作的是汇编代码，难以进行编译优化，而可以执行编译优化的环节，却没有跨文件的全局信息。这样的编译框架，虽然提高了编译效率，每次重新编译只需要编译修改过的少量编译单元，但也丢失了许多跨文件的优化机会。 + +链接时优化（LTO）， 设计的初衷就是希望能够在链接时，拥有跨编译单元的调用信息的时候，进行编译优化，提供更多的优化机会。为了达到这个目的，LTO 需要将编译优化所需的 IR 信息保留到链接时。在链接时，链接器会调用 LTO 插件，执行全程序分析，生成更加有效的优化决策，再经由编译优化生成更高效的IR，进一步转成包含汇编代码的目标对象文件，最后由链接器完成常规的链接工作。 + +# 版本构建使能 + +## 背景 + +为了获得更优的性能与更小的二进制体积，许多海外社区已经在版本构建中使用了链接时优化，链接时优化也正在成为各方寻找编译优化机会的新战场。openEuler 计划从 24.09 创新版本开始，在版本构建中引入 LTO。 + +## 方案 + +我们将在 openEuler-rpm-config 的 macro 中所包含的全局编译选项中插入 `-flto -ffat-lto-objects` ，以达到在构建软件包是使能 lto 的效果。其中 `-flto` 用以使能链接时优化，而 `-ffat-lto-objects` 用以生成同时包含 LTO 对象信息和常规链接所需的汇编信息的胖目标对象。在当前构建中，LTO 对象信息会参与 LTO 优化，而由于 LTO 目标对象文件在不同版本的 gcc 之间是不通用的，因此在打包生成对应的 `.rpm` 包之前，我们会将 `.o/.a` 文件中的 LTO 相关字段给消除，仅保留常规链接所需的汇编代码信息，不对静态库本身产生影响。 + +## 使能范围 + +由于 LTO 的编译流程与常规的编译流程相差较大，影响较广，为了控制 LTO 对版本质量的冲击，我们当前仅对 500+ 个软件包使能了 lto，你可以在 `/usr/lib/rpm/%{_vendor}/lto_white_list` 中找到这些软件包的清单。这些白名单应用在使能了 LTO 之后构建成功，并通过了自带的测试套。lto 编译选项仅在构建白名单应用时被设置为 `-flto -ffat-lto-objects`，否则置为空。 + +我们会在后续的创新版本上，联合应用维护者，扩大 LTO 使能的范围。 + +## 注意事项 + +当前热补丁机制与 LTO 仍存在不兼容，热补丁在 LTO 开启时会失效。我们已与热补丁团队就解决方式达成一致，会在后续版本中解决该问题。 \ No newline at end of file diff --git a/docs/zh/docs/Gazelle/Gazelle.md b/docs/zh/docs/Gazelle/Gazelle.md index a40b562a7a6f64a10e8a519bee4e7ab26e61ec54..7dfbbbf4875468a244369c9b5453fe57c8781a74 100644 --- a/docs/zh/docs/Gazelle/Gazelle.md +++ b/docs/zh/docs/Gazelle/Gazelle.md @@ -12,7 +12,7 @@ Gazelle是一款高性能用户态协议栈。它基于DPDK在用户态直接读 完全兼容POSIX，零修改，适用不同类型的应用。 - 单进程且网卡支持多队列时，只需使用liblstack.so有更短的报文路径。其余场景使用ltran进程分发报文到各个线程。 + 单进程且网卡支持多队列时，只需使用liblstack.so有更短的报文路径。 ## 安装 @@ -36,22 +36,7 @@ dpdk >= 21.11-2 ### 1. 使用root权限安装ko -根据实际情况选择使用ko，提供虚拟网口、绑定网卡到用户态功能。 -若使用虚拟网口功能，则使用rte_kni.ko。 - -```sh -modprobe rte_kni carrier="on" -``` - -配置NetworkManager不托管kni网卡 - -```sh -[root@localhost ~]# cat /etc/NetworkManager/conf.d/99-unmanaged-devices.conf -[keyfile] -unmanaged-devices=interface-name:kni -[root@localhost ~]# systemctl reload NetworkManager -``` - +根据实际情况选择使用ko，提供绑定网卡到用户态功能。 网卡从内核驱动绑为用户态驱动的ko，根据实际情况选择一种。 ```sh @@ -99,21 +84,15 @@ cat查询实际预留页个数，连续内存不足时可能比预期少 ### 4. 挂载大页内存 -创建两个目录，分别给lstack的进程、ltran进程访问大页内存使用。操作步骤如下： +创建目录，给lstack的进程访问大页内存使用。操作步骤如下： ```sh -mkdir -p /mnt/hugepages-ltran mkdir -p /mnt/hugepages-lstack -chmod -R 700 /mnt/hugepages-ltran chmod -R 700 /mnt/hugepages-lstack -mount -t hugetlbfs nodev /mnt/hugepages-ltran -o pagesize=2M mount -t hugetlbfs nodev /mnt/hugepages-lstack -o pagesize=2M ``` ->说明： -/mnt/hugepages-ltran和/mnt/hugepages-lstack必须挂载同样pagesize大页 - ### 5. 应用程序使用Gazelle 有两种使用Gazelle方法，根据需要选择其一 @@ -150,31 +129,36 @@ gcc test.c -o test ${LSTACK_LIBS} |选项|参数格式|说明| |:---|:---|:---| -|dpdk_args|--socket-mem（必需）
--huge-dir（必需）
--proc-type（必需）
--legacy-mem
--map-perfect
-d|dpdk初始化参数，参考dpdk说明
--map-perfect为扩展特性，用于防止dpdk占用多余的地址空间，保证ltran有额外的地址空间分配给lstack。
-d参数加载指定so库文件| +|dpdk_args|--socket-mem（必需）
--huge-dir（必需）
--proc-type（必需）
--legacy-mem
--map-perfect
-d|dpdk初始化参数，参考dpdk说明
--map-perfect为扩展特性，用于防止dpdk占用多余的地址空间，保证有额外的地址空间分配给lstack。
-d参数加载指定so库文件| |listen_shadow| 0/1 | 是否使用影子fd监听。单listen线程，多协议栈线程时是能| -|use_ltran| 0/1 | 是否使用ltran | +|use_ltran| 0/1 | 是否使用ltran ，功能已衰退，不再支持| |num_cpus|"0,2,4 ..."|lstack线程绑定的cpu编号，编号的数量为lstack线程个数(小于等于网卡多队列数量)。可按NUMA选择cpu| -|num_wakeup|"1,3,5 ..."|wakeup线程绑定的cpu编号，编号的数量为wakeup线程个数，与lstack线程的数量保持一致。与numcpus选择对应NUMA的cpu。不配置则为不使用唤醒线程| |low_power_mode|0/1|是否开启低功耗模式，暂不支持| -|kni_switch|0/1|rte_kni开关，默认为0。只有不使用ltran时才能开启| +|kni_switch|0/1|rte_kni开关，默认为0。功能已衰退，不再支持| |unix_prefix|"string"|gazelle进程间通信使用的unix socket文件前缀字符串，默认为空，和需要通信的ltran.conf的unix_prefix或gazellectl的-u参数配置一致。不能含有特殊字符，最大长度为128。| |host_addr|"192.168.xx.xx"|协议栈的IP地址，也是应用程序的IP地址| |mask_addr|"255.255.xx.xx"|掩码地址| |gateway_addr|"192.168.xx.1"|网关地址| -|devices|"aa:bb:cc:dd:ee:ff"|网卡通信的mac地址，需要与ltran.conf的bond_macs配置一致| +|devices|"aa:bb:cc:dd:ee:ff"|网卡通信的mac地址，在bond1模式下作为bond的主网口| |app_bind_numa|0/1|应用的epoll和poll线程是否绑定到协议栈所在的numa，缺省值是1，即绑定| |send_connect_number|4|设置为正整数，表示每次协议栈循环中发包处理的连接个数| |read_connect_number|4|设置为正整数，表示每次协议栈循环中收包处理的连接个数| |rpc_number|4|设置为正整数，表示每次协议栈循环中rpc消息处理的个数| |nic_read_num|128|设置为正整数，表示每次协议栈循环中从网卡读取的数据包的个数| -|mbuf_pool_size|1024000|设置为小于5120000的正整数，表示初始化时申请的mbuf地址池大小，需要根据网卡硬件支持进行合理配置，配置过小会启动失败| +|bond_mode|-1|设置组bond，当前支持两个网口组bond模式，默认值-1关闭bond，当前支持bond1/4/6| +|bond_slave_mac|"aa:bb:cc:dd:ee:ff;AA:BB:CC:DD:EE:FF"|设置组bond网口的mac地址信息，以;分隔| +|bond_miimon|10|设置bond模式的监听间隔，默认值10，取值范围0~1500| +|udp_enable|0/1|是否开启udp功能，默认值1开启| +|nic_vlan_mode|-1|是否开启vlan模式，默认值-1关闭，取值范围-1~4095，0和4095是业界通用预留id无实际效果| +|tcp_conn_count|1500|tcp的最大连接数，该参数乘以mbuf_count_per_conn是初始化时申请的mbuf池大小，配置过小会启动失败，tcp_conn_count * mbuf_count_per_conn * 2048字节不能大于大页大小 | +|mbuf_count_per_conn|170|每个tcp连接需要的mbuf个数，该参数乘以tcp_conn_count是初始化时申请的mbuf地址池大小，配置过小会启动失败，tcp_conn_count * mbuf_count_per_conn * 2048字节不能大于大页大小| lstack.conf示例： ```sh dpdk_args=["--socket-mem", "2048,0,0,0", "--huge-dir", "/mnt/hugepages-lstack", "--proc-type", "primary", "--legacy-mem", "--map-perfect"] -use_ltran=1 +use_ltran=0 kni_switch=0 low_power_mode=0 @@ -192,56 +176,15 @@ read_connect_number=4 rpc_number=4 nic_read_num=128 mbuf_pool_size=1024000 -``` - -- ltran.conf用于指定ltran启动的参数，默认路径为/etc/gazelle/ltran.conf。使用ltran时，lstack.conf内配置use_ltran=1,配置参数如下： - -|选项|参数格式|说明| -|:---|:---|:---| -|forward_kit|"dpdk"|指定网卡收发模块。
保留字段，目前未使用。| -|forward_kit_args|-l
--socket-mem(必需)
--huge-dir(必需)
--proc-TYPE(必需)
--legacy-mem(必需)
--map-perfect(必需)
-d|dpdk初始化参数，参考dpdk说明。
--map-perfect为扩展特性，用于防止dpdk占用多余的地址空间，保证ltran有额外的地址空间分配给lstack。
-d参数加载指定so库文件| -|kni_switch|0/1|rte_kni开关，默认为0| -|unix_prefix|"string"|gazelle进程间通信使用的unix socket文件前缀字符串，默认为空，和需要通信的lstack.conf的unix_prefix或gazellectl的-u参数配置一致| -|dispatch_max_clients|n|ltran支持的最大client数。
lstack的协议栈线程总数不大于32| -|dispatch_subnet|192.168.xx.xx|子网掩码，表示ltran能识别的IP所在子网网段。参数为样例，子网按实际值配置。| -|dispatch_subnet_length|n|子网长度，表示ltran能识别的子网长度，例如length为4时，192.168.1.1-192.168.1.16| -|bond_mode|n|bond模式，目前只支持Active Backup(Mode1)，取值为1| -|bond_miimon|n|bond链路监控时间，单位为ms，取值范围为1到2^64 - 1 - (1000 * 1000)| -|bond_ports|"0x01"|使用的dpdk网卡，0x01表示第一块| -|bond_macs|"aa:bb:cc:dd:ee:ff"|绑定的网卡mac地址，需要跟kni的mac地址保持一致| -|bond_mtu|n|最大传输单元，默认是1500，不能超过1500，最小值为68，不能低于68| - -ltran.conf示例： - -```sh -forward_kit_args="-l 0,1 --socket-mem 1024,0,0,0 --huge-dir /mnt/hugepages-ltran --proc-type primary --legacy-mem --map-perfect --syslog daemon" -forward_kit="dpdk" - -kni_switch=0 - -dispatch_max_clients=30 -dispatch_subnet="192.168.1.0" -dispatch_subnet_length=8 - bond_mode=1 -bond_mtu=1500 -bond_miimon=100 -bond_macs="aa:bb:cc:dd:ee:ff" -bond_ports="0x1" - -tcp_conn_scan_interval=10 +bond_slave_mac="aa:bb:cc:dd:ee:ff;AA:BB:CC:DD:EE:FF" +udp_enable=1 +nic_vlan_mode=-1 ``` -### 7. 启动应用程序 - -- 启动ltran进程 - - 单进程且网卡支持多队列，则直接使用网卡多队列分发报文到各线程，不启动ltran进程，lstack.conf的use_ltran配置为0. - 启动ltran时不使用-config-file指定配置文件，则使用默认路径/etc/gazelle/ltran.conf +- ltran模式功能已衰退，多进程使用需求可尝试使用SR-IOV组网硬件虚拟化组网模式： - ```sh - ltran --config-file ./ltran.conf - ``` +### 7. 启动应用程序 - 启动应用程序 @@ -258,40 +201,29 @@ Gazelle wrap应用程序POSIX接口，应用程序无需修改代码。 ### 9. 调测命令 -- 不使用ltran模式时不支持gazellectl ltran xxx命令，以及gazellectl lstack show {ip | pid} -r命令 - ```sh Usage: gazellectl [-h | help] - or: gazellectl ltran {quit | show | set} [LTRAN_OPTIONS] [time] [-u UNIX_PREFIX] or: gazellectl lstack {show | set} {ip | pid} [LSTACK_OPTIONS] [time] [-u UNIX_PREFIX] - quit ltran process exit - - where LTRAN_OPTIONS := - show ltran all statistics - -r, rate show ltran statistics per second - -i, instance show ltran instance register info - -b, burst show ltran NIC packet len per second - -l, latency show ltran latency - set: - loglevel {error | info | debug} set ltran loglevel - where LSTACK_OPTIONS := show lstack all statistics -r, rate show lstack statistics per second -s, snmp show lstack snmp -c, connetct show lstack connect -l, latency show lstack latency + -x, xstats show lstack xstats + -k, nic-features show state of protocol offload and other feature + -a, aggregatin [time] show lstack send/recv aggregation set: loglevel {error | info | debug} set lstack loglevel lowpower {0 | 1} set lowpower enable [time] measure latency time default 1S ``` --u参数指定gazelle进程间通信的unix socket前缀，和需要通信的ltran.conf或lstack.conf的unix_prefix配置一致。 +-u参数指定gazelle进程间通信的unix socket前缀，和需要通信的lstack.conf的unix_prefix配置一致。 **抓包工具** -gazelle使用的网卡由dpdk接管，因此普通的tcpdump无法抓到gazelle的数据包。作为替代，gazelle使用dpdk-tools软件包中提供的gazelle-pdump作为数据包捕获工具，它使用dpdk的多进程模式和lstack/ltran进程共享内存。在ltran模式下，gazelle-pdump只能抓取和网卡直接通信的ltran的数据包，通过tcpdump的数据包过滤，可以过滤特定lstack的数据包。 +gazelle使用的网卡由dpdk接管，因此普通的tcpdump无法抓到gazelle的数据包。作为替代，gazelle使用dpdk-tools软件包中提供的gazelle-pdump作为数据包捕获工具，它使用dpdk的多进程模式和lstack进程共享内存。 [详细使用方法](https://gitee.com/openeuler/gazelle/blob/master/doc/pdump.md) **线程名绑定** @@ -316,11 +248,9 @@ lstack启动时可以通过指定环境变量GAZELLE_THREAD_NAME来指定lstack - 不支持accept阻塞模式或者connect阻塞模式。 - 最多支持1500个TCP连接。 -- 当前仅支持TCP、ICMP、ARP、IPv4 协议。 +- 当前仅支持TCP、ICMP、ARP、IPv4、UDP 协议。 - 在对端ping Gazelle时，要求指定报文长度小于等于14000B。 - 不支持使用透明大页。 -- ltran不支持使用多种类型的网卡混合组bond。 -- ltran的bond1主备模式，只支持链路层故障主备切换（例如网线断开），不支持物理层故障主备切换（例如网卡下电、拔网卡）。 - 虚拟机网卡不支持多队列。 ### 操作约束 @@ -328,24 +258,25 @@ lstack启动时可以通过指定环境变量GAZELLE_THREAD_NAME来指定lstack - 提供的命令行、配置文件默认root权限。非root用户使用，需先提权以及修改文件所有者。 - 将用户态网卡绑回到内核驱动，必须先退出Gazelle。 - 大页内存不支持在挂载点里创建子目录重新挂载。 -- ltran需要最低大页内存为1GB。 - 每个应用实例协议栈线程最低大页内存为800MB 。 - 仅支持64位系统。 - 构建x86版本的Gazelle使用了-march=native选项，基于构建环境的CPU（Intel® Xeon® Gold 5118 CPU @ 2.30GHz指令集进行优化。要求运行环境CPU支持 SSE4.2、AVX、AVX2、AVX-512 指令集。 - 最大IP分片数为10（ping 最大包长14790B），TCP协议不使用IP分片。 - sysctl配置网卡rp_filter参数为1，否则可能不按预期使用Gazelle协议栈，而是依然使用内核协议栈。 -- 不使用ltran模式，KNI网口不可配置只支持本地通讯使用，且需要启动前配置NetworkManager不管理KNI网卡。 -- 虚拟KNI网口的IP及mac地址，需要与lstack.conf配置文件保持一致 。 +- 不支持使用多种类型的网卡混合组bond。 +- bond1主备模式，只支持链路层故障主备切换（例如网线断开），不支持物理层故障主备切换（例如网卡下电、拔网卡）。 +- 发送udp报文包长超过45952(32 * 1436)B时，需要将send_ring_size扩大为至少64个。 ## 注意事项 用户根据使用场景评估使用Gazelle +ltran模式及kni模块由于上游社区及依赖包变更,功能在新版本中不再支持. + 共享内存 - 现状 - 大页内存 mount 至 /mnt/hugepages-lstack 目录，进程初始化时在 /mnt/hugepages-lstack 目录下创建文件，每个文件对应一个大页，并 mmap 这些文件。ltran 在收到 lstask 的注册信息后，根据大页内存配置信息页 mmap 目录下文件，实现大页内存共享。 - ltran 在 /mnt/hugepages-ltran 目录的大页内存同理。 + 大页内存 mount 至 /mnt/hugepages-lstack 目录，进程初始化时在 /mnt/hugepages-lstack 目录下创建文件，每个文件对应一个大页，并 mmap 这些文件。 - 当前消减措施 大页文件权限 600，只有 OWNER 用户才能访问文件，默认 root 用户，支持配置成其他用户； 大页文件有 DPDK 文件锁，不能直接写或者映射。 @@ -356,4 +287,4 @@ lstack启动时可以通过指定环境变量GAZELLE_THREAD_NAME来指定lstack Gazelle没有做流量限制，用户有能力发送最大网卡线速流量的报文到网络，可能导致网络流量拥塞。 **进程仿冒** -合法注册到ltran的两个lstack进程，进程A可仿冒进程B发送仿冒消息给ltran，修改ltran的转发控制信息，造成进程B通讯异常，进程B报文转发给进程A信息泄露等问题。建议lstack进程都为可信任进程。 +建议lstack进程都为可信任进程。 diff --git a/docs/zh/docs/HSAK/hsak_tools_usage.md b/docs/zh/docs/HSAK/hsak_tools_usage.md index 847e786b1a608b6b3b2d679df18e55ae16739383..c74beb7e83d9e49cf2667adebfef2a8ae6aff6cd 100644 --- a/docs/zh/docs/HSAK/hsak_tools_usage.md +++ b/docs/zh/docs/HSAK/hsak_tools_usage.md @@ -43,7 +43,7 @@ libstorage-shutdown reset
| - | -- | -- | -- | -
|---|---|---|---|
| - | -- | -- | -- | -
| - | -- | -- | -- | -
| - | -- | -- | -- | -
| - - | -- | -- | -- | -
说明：
服务器要求配置Avago 3508 RAID控制卡和启用LOM-X722网卡| +openEuler安装时，应注意硬件兼容性方面的问题，当前已支持的服务器类型请参考[兼容性列表](https://www.openeuler.org/zh/compatibility/)。 ### 最小硬件要求 diff --git "a/docs/zh/docs/Installation/\345\256\211\350\243\205\346\214\207\345\257\274.md" "b/docs/zh/docs/Installation/\345\256\211\350\243\205\346\214\207\345\257\274.md" index 2caae5a352479380c1525be1386a7d01a49f76bf..e16b25aa12ce1bb5fe764762f2ae38c09da80956 100644 --- "a/docs/zh/docs/Installation/\345\256\211\350\243\205\346\214\207\345\257\274.md" +++ "b/docs/zh/docs/Installation/\345\256\211\350\243\205\346\214\207\345\257\274.md" @@ -141,21 +141,19 @@ - http 或 https 方式 - http 或 https 方式的安装源如下图所示。 + http 或 https 方式的安装源如下图所示。输入框内容以实际版本发布的安装源地址为准，如
2.“opstype=upgrade/rollback”时，代表升级/回退后配置，即在升级/回退重启后进行配置，详细字段说明请见[配置（Settings）指导](#配置settings指导) | “opstype=config”时必选 | + | upgradeconfigs | / | 升级前配置设置 | 在升级或者回退时有效，在升级或者回退操作之前起效，详细字段说明请见[配置（Settings）指导](#配置settings指导)| 可选 | + | nodeselector | string | 需要进行升级/配置/回滚操作的节点label | 用于只对具有某些特定label的节点而不是集群所有worker节点进行运维的场景，需要进行运维操作的节点需要包含key为upgrade.openeuler.org/node-selector的label，nodeselector为该label的value值。
注意事项：
1.此参数不配置时，或者配置为“no-label”时对没有upgrade.openeuler.org/node-selector的节点进行操作
2.此参数为“”时，对具有upgrade.openeuler.org/node-selector=“”的节点进行操作
3.如需忽略label，对所有节点进行操作，需指定此参数为all-label| 可选 | + | timewindow | / | 升级/配置/回滚操作的时间窗口 |1.指定时间窗口时starttime和endtime都需指定，即二者需要同时为空或者同时不为空
2.starttime和endtime类型为string，需要为YYYY-MM-DD HH:MM:SS格式或者HH:MM:SS格式，且二者格式需一致
3.为HH:MM:SS格式时，starttime < endtime认为starttime是下一天的该时间
4.timewindow不配置时默认为不存在时间窗限制| 可选 | + | timeinterval | int | 升级/配置/回滚操作每批次任务下发的时间间隔 |参数单位为秒，时间间隔为operator下发任务的时间间隔，如k8s集群繁忙无法立即响应operator请求，实际时间间隔可能会大于指定时间| 可选 | + | executionmode | string | 升级/配置/回滚操作执行的方式 |仅支持serial或者parallel，即串行或者并行，当次参数不设置时，默认采用并行的方式| 可选 | ## 升级指导 -在集群中创建类别为OS的定制对象，设置相应字段。类别OS来自于安装和部署章节创建的CRD对象，字段及说明如下： +1.编写YAML文件，在集群中部署 OS 的cr实例，用于部署cr实例的YAML示例如下，假定将上面的YAML保存到upgrade_v1alpha1_os.yaml; + * 使用磁盘镜像进行升级 + + ```yaml + apiVersion: upgrade.openeuler.org/v1alpha1 + kind: OS + metadata: + name: os-sample + spec: + imagetype: disk + opstype: upgrade + osversion: edit.os.version + maxunavailable: edit.node.upgrade.number + containerimage: "" + evictpodforce: true/false + imageurl: edit.image.url + checksum: image.checksum + flagSafe: imageurl.safety + mtls: imageurl use mtls or not + cacert: ca certificate + clientcert: client certificate + clientkey: client certificate key + ``` + + * 使用容器镜像进行升级 + * 使用容器镜像进行升级前请先制作升级所需的容器镜像，制作方式请见[《容器OS镜像制作指导》](./容器OS镜像制作指导.md)中 [KubeOS OCI 镜像制作](./容器OS镜像制作指导.md#kubeos-oci-镜像制作)。 + * 节点容器引擎为docker + + ``` yaml + apiVersion: upgrade.openeuler.org/v1alpha1 + kind: OS + metadata: + name: os-sample + spec: + imagetype: docker + opstype: upgrade + osversion: edit.os.version + maxunavailable: edit.node.upgrade.number + containerimage: container image like repository/name:tag + evictpodforce: true/false + imageurl: "" + checksum: container image digests + flagSafe: false + mtls: true + ``` + + * 节点容器引擎为containerd + + ```yaml + apiVersion: upgrade.openeuler.org/v1alpha1 + kind: OS + metadata: + name: os-sample + spec: + imagetype: containerd + opstype: upgrade + osversion: edit.os.version + maxunavailable: edit.node.upgrade.number + containerimage: container image like repository/name:tag + evictpodforce: true/false + imageurl: "" + checksum: container image digests + flagSafe: false + mtls: true + ``` + + * 升级并且进行配置的示例如下： + * 以节点容器引擎为containerd为例，升级方式对配置无影响，upgradeconfigs在升级前起效，sysconfigs在升级后起效，配置参数说明请见[配置（Settings）指导](#配置settings指导)。 + * 升级并且配置时opstype字段需为upgrade。 + * upgradeconfig为升级之前执行的配置，sysconfigs为升级机器重启后执行的配置，用户可按需进行配置。 + + ```yaml + apiVersion: upgrade.openeuler.org/v1alpha1 + kind: OS + metadata: + name: os-sample + spec: + imagetype: "" + opstype: upgrade + osversion: edit.os.version + maxunavailable: edit.node.upgrade.number + containerimage: "" + evictpodforce: true/false + imageurl: "" + checksum: container image digests + flagSafe: false + mtls: false + sysconfigs: + version: edit.os.version + configs: + - model: kernel.sysctl + contents: + - key: kernel param key1 + value: kernel param value1 + - key: kernel param key2 + value: kernel param value2 + - model: kernel.sysctl.persist + configpath: persist file path + contents: + - key: kernel param key3 + value: kernel param value3 + - key: "" + value: "" + upgradeconfigs: + version: 1.0.0 + configs: + - model: kernel.sysctl + contents: + - key: kernel param key4 + value: kernel param value4 + ``` + * 设置nodeselector、timewindow、timeinterval、executionmode升级部分节点示例如下： + * 以节点容器引擎为containerd为例，升级方式对节点筛选无影响。 + * 需要进行升级的节点需包含key为`upgrade.openeuler.org/node-selector`的label，nodeselector的值为该label的value，即假定nodeselector值为kubeos，则只对包含`upgrade.openeuler.org/node-selector=kubeos`的label的worker节点进行升级。 + * nodeselector、timewindow、timeinterval、executionmode对配置和回滚同样有效。 + * 节点添加label、修改label、删除label和查看label命令示例如下： + ``` shell + # 为节点kubeos-node1增加label + kubectl label nodes kubeos-node1 upgrade.openeuler.org/node-selector=kubeos-v1 + # 修改节点kubeos-node1的label + kubectl label --overwrite nodes kubeos-node1 upgrade.openeuler.org/node-selector=kubeos-v2 + # 删除节点kubeos-node1的label + kubectl label nodes kubeos-node1 upgrade.openeuler.org/node-selector- + # 查看节点的label + kubectl get nodes --show-labels + ``` + * yaml示例如下： + ```yaml + apiVersion: upgrade.openeuler.org/v1alpha1 + kind: OS + metadata: + name: os-sample + spec: + imagetype: containerd + opstype: upgrade + osversion: edit.os.version + maxunavailable: edit.node.upgrade.number + containerimage: container image like repository/name:tag + evictpodforce: true/false + imageurl: "" + checksum: container image digests + flagSafe: false + mtls: true + nodeselector: edit.node.label.key + timewindow: + starttime: "HH::MM::SS/YYYY-MM-DD HH::MM::SS" + endtime: "HH::MM::SS/YYYY-MM-DD HH::MM::SS" + timeinterval: time intervel like 30 + executionmode: serial/parallel + ``` + +2. 查看未升级的节点的 OS 版本。 + + ```shell + kubectl get nodes -o custom-columns='NAME:.metadata.name,OS:.status.nodeInfo.osImage' + ``` -| 参数 |参数类型 | 参数说明 | 使用说明 | 是否必选 | -| -------------- | ------ | ------------------------------------------------------------ | ----- | ---------------- | -| imagetype | string | 使用的升级镜像的类型 | 需为 docker 或者 disk ，其他值无效，且该参数仅在升级场景有效|是 | -| opstype | string | 进行的操作，升级或者回退 | 需为 upgrade ，或者 rollback ，其他值无效 |是 | -| osversion | string | 用于升级或回退的镜像的OS版本 | 需为 KubeOS version , 例如: KubeOS 1.0.0|是 | -| maxunavailable | int | 同时进行升级或回退的节点数 | maxunavailable值设置为大于实际集群的节点数时也可正常部署，升级或回退时会按照集群内实际节点数进行|是 | -| dockerimage | string | 用于升级的容器镜像 | 需要为容器镜像格式：repository/name:tag，仅在使用容器镜像升级场景下有效|是 | -| imageurl | string | 用于升级的磁盘镜像的地址 | imageurl中包含协议，只支持http或https协议，例如：https://192.168.122.15/update.img 仅在使用磁盘镜像升级场景下有效|是 | -| checksum | string | 用于升级的磁盘镜像校验的checksum(SHA-256)值 | 仅在使用磁盘镜像升级场景下有效 |是 | -| flagSafe | bool | 当imageurl的地址使用http协议表示是否是安全的 | 需为 true 或者 false ，仅在imageurl使用http协议时有效 |是 | -| mtls | bool | 用于表示与imageurl连接是否采用https双向认证 | 需为 true 或者 false ，仅在imageurl使用https协议时有效|是 | -| cacert | string | https或者https双向认证时使用的根证书文件 | 仅在imageurl使用https协议时有效| imageurl使用https协议时必选 | -| clientcert | string | https双向认证时使用的客户端证书文件 | 仅在使用https双向认证时有效|mtls为true时必选 | -| clientkey | string | https双向认证时使用的客户端公钥 | 仅在使用https双向认证时有效|mtls为true时必选 | +3. 执行命令，在集群中部署cr实例后，节点会根据配置的参数信息进行升级。 -imageurl指定的地址里包含协议，只支持http或https协议。imageurl为https协议时为安全传输，imageurl为http地址时，需指定flagSafe为true，即用户明确该地址为安全时，才会下载镜像。如imageurl为http地址且没有指定flagSafe为true，默认该地址不安全，不会下载镜像并且在升级节点的日志中提示用户该地址不安全 + ```shell + kubectl apply -f upgrade_v1alpha1_os.yaml + ``` -对于imageurl，推荐使用https协议，使用https协议需要升级的机器已安装相应证书。如果镜像服务器由用户自己维护，需要用户自己进行签名，并保证升级节点已安装对应证书。用户需要将证书放在容器OS /etc/KubeOS/certs目录下。地址由管理员传入，管理员应该保证网址的安全性，推荐采用内网地址。 +4. 再次查看节点的 OS 版本来确认节点是否升级完成。 -容器OS镜像的合法性检查需要由容器OS镜像服务提供者做合法性检查，确保下载的容器OS镜像来源可靠 + ```shell + kubectl get nodes -o custom-columns='NAME:.metadata.name,OS:.status.nodeInfo.osImage' + ``` -编写YAML文件，在集群中部署 OS 的cr实例，用于部署cr实例的YAML示例如下： +> **说明**： +> +> 如果后续需要再次升级，与上面相同对 upgrade_v1alpha1_os.yaml 的 相应字段进行相应修改。 -* 使用磁盘镜像进行升级 +## 配置（Settings）指导 - ``` - apiVersion: upgrade.openeuler.org/v1alpha1 - kind: OS - metadata: - name: os-sample - spec: - imagetype: disk - opstype: upgrade - osversion: edit.os.version - maxunavailable: edit.node.upgrade.number - dockerimage: "" - imageurl: edit.image.url - checksum: image.checksum - flagSafe: imageurl.safety - mtls: imageurl use mtls or not - cacert: ca certificate - clientcert: client certificate - clientkey: client certificate key - ``` +* Settings参数说明: -* 使用容器镜像升级 + 基于示例YAML对配置的参数进行说明，示例YAML如下，配置的格式（缩进）需和示例保持一致： - ``` shell + ```yaml apiVersion: upgrade.openeuler.org/v1alpha1 kind: OS metadata: name: os-sample spec: - imagetype: docker - opstype: upgrade + imagetype: "" + opstype: config osversion: edit.os.version - maxunavailable: edit.node.upgrade.number - dockerimage: dockerimage like repository/name:tag - imageurl: "" + maxunavailable: edit.node.config.number + containerimage: "" + evictpodforce: false checksum: "" - flagSafe: false - mtls: true + sysconfigs: + version: edit.sysconfigs.version + configs: + - model: kernel.sysctl + contents: + - key: kernel param key1 + value: kernel param value1 + - key: kernel param key2 + value: kernel param value2 + operation: delete + - model: kernel.sysctl.persist + configpath: persist file path + contents: + - key: kernel param key3 + value: kernel param value3 + - model: grub.cmdline.current + contents: + - key: boot param key1 + - key: boot param key2 + value: boot param value2 + - key: boot param key3 + value: boot param value3 + operation: delete + - model: grub.cmdline.next + contents: + - key: boot param key4 + - key: boot param key5 + value: boot param value5 + - key: boot param key6 + value: boot param value6 + operation: delete ``` - 使用容器镜像进行升级前请先制作升级所需的容器镜像，制作方式请见《容器OS镜像制作指导》 + 配置的参数说明如下： -假定将上面的YAML保存到upgrade_v1alpha1_os.yaml + | 参数 | 参数类型 | 参数说明 | 使用说明 | 配置中是否必选 | + | ---------- | -------- | --------------------------- | ------------------------------------------------------------ | ----------------------- | + | version | string | 配置的版本 | 通过version是否相等来判断配置是否触发，version为空（为""或者没有值）时同样进行判断，所以不配置sysconfigs/upgradeconfigs时，继存的version值会被清空并触发配置。 | 是 | + | configs | / | 具体配置内容 | 包含具体配置项列表。 | 是 | + | model | string | 配置的类型 | 支持的配置类型请看附录下的[Settings列表](#setting-列表) | 是 | + | configpath | string | 配置文件路径 | 仅在kernel.sysctl.persist配置类型中生效，请看附录下的[Settings列表](#setting-列表)对配置文件路径的说明。 | 否 | + | contents | / | 具体key/value的值及操作类型 | 包含具体配置参数列表。 | 是 | + | key | string | 参数名称 | key不能为空，不能包含"="，不建议配置含空格、tab键的字符串，具体请看附录下的[Settings列表](#setting-列表)中每种配置类型对key的说明。 | 是 | + | value | string | 参数值 | key=value形式的参数中，value不能为空，不建议配置含空格、tab键的字符串，具体请看附录下的[Settings列表](#setting-列表)中对每种配置类型对value的说明。 | key=value形式的参数必选 | + | operation | string | 对参数进行的操作 | 仅对kernel.sysctl.persist、grub.cmdline.current、grub.cmdline.next类型的参数生效。默认为添加或更新。仅支持配置为delete，代表删除已存在的参数（key=value需完全一致才能删除）。 | 否 | -查看未升级的节点的 OS 版本 + * upgradeconfigs与sysconfigs参数相同，upgradeconfigs为升级/回退前进行的配置，仅在upgrade/rollback场景起效，sysconfigs既支持只进行配置，也支持在升级/回退重启后进行配置。 -``` -kubectl get nodes -o custom-columns='NAME:.metadata.name,OS:.status.nodeInfo.osImage' -``` +* 使用说明 -执行命令，在集群中部署cr实例后，节点会根据配置的参数信息进行升级。 + * 编写YAML文件，在集群中部署 OS 的cr实例，用于部署cr实例的YAML示例如上，假定将上面的YAML保存到upgrade_v1alpha1_os.yaml。 -``` -kubectl apply -f upgrade_v1alpha1_os.yaml -``` + * 查看配置之前的节点的配置的版本和节点状态（NODESTATUS状态为idle）。 -再次查看节点的 OS 版本来确认节点是否升级完成 + ```shell + kubectl get osinstances -o custom-columns='NAME:.metadata.name,NODESTATUS:.spec.nodestatus,SYSCONFIG:status.sysconfigs.version,UPGRADECONFIG:status.upgradeconfigs.version' + ``` -``` -kubectl get nodes -o custom-columns='NAME:.metadata.name,OS:.status.nodeInfo.osImage' -``` + * 执行命令，在集群中部署cr实例后，节点会根据配置的参数信息进行配置，再次查看节点状态(NODESTATUS变成config)。 -> **说明**： -> -> 如果后续需要再次升级，与上面相同对 upgrade_v1alpha1_os.yaml 的 imageurl ，osversion，checksum，maxunavailable，flagSafe 或者dockerimage字段进行相应修改。 + ```shell + kubectl apply -f upgrade_v1alpha1_os.yaml + kubectl get osinstances -o custom-columns='NAME:.metadata.name,NODESTATUS:.spec.nodestatus,SYSCONFIG:status.sysconfigs.version,UPGRADECONFIG:status.upgradeconfigs.version' + ``` + + * 再次查看节点的配置的版本确认节点是否配置完成(NODESTATUS恢复为idle)。 + + ```shell + kubectl get osinstances -o custom-columns='NAME:.metadata.name,NODESTATUS:.spec.nodestatus,SYSCONFIG:status.sysconfigs.version,UPGRADECONFIG:status.upgradeconfigs.version' + ``` + +* 如果后续需要再次配置，与上面相同对 upgrade_v1alpha1_os.yaml 的相应字段进行相应修改。 ## 回退指导 ### 使用场景 -- 虚拟机无法正常启动时，需要退回到上一可以启动的版本时进行回退操作，仅支持手动回退容器 OS 。 -- 虚拟机能够正常启动并且进入系统，需要将当前版本退回到老版本时进行回退操作，支持工具回退（类似升级方式）和手动回退，建议使用工具回退。 +* 虚拟机无法正常启动时，可在grub启动项页面手动切换启动项，使系统回退至上一版本（即手动回退）。 +* 虚拟机能够正常启动并且进入系统时，支持工具回退和手动回退，建议使用工具回退。 +* 工具回退有两种方式： + 1. rollback模式直接回退至上一版本。 + 2. upgrade模式重新升级至上一版本。 -### 手动回退 +### 手动回退指导 -手动重启虚拟机，选择第二启动项进行回退，手动回退仅支持回退到本次升级之前的版本。 +* 手动重启虚拟机，进入启动项页面后，选择第二启动项进行回退，手动回退仅支持回退到上一个版本。 -### 工具回退 +### 工具回退指导 -* 回退至任意版本 - * 修改 OS 的cr实例的YAML 配置文件（例如 upgrade_v1alpha1_os.yaml），设置相应字段为期望回退的老版本镜像信息。类别OS来自于安装和部署章节创建的CRD对象，字段说明及示例请见上一节升级指导。 +* 回退至任意版本 + 1. 修改 OS 的cr实例的YAML 配置文件（例如 upgrade_v1alpha1_os.yaml），设置相应字段为期望回退的老版本镜像信息。类别OS来自于安装和部署章节创建的CRD对象，字段说明及示例请见上一节升级指导。 - * YAML修改完成后执行更新命令，在集群中更新定制对象后，节点会根据配置的字段信息进行回退 + 2. YAML修改完成后执行更新命令，在集群中更新定制对象后，节点会根据配置的字段信息进行回退 - ``` - kubectl apply -f upgrade_v1alpha1_os.yaml - ``` + ```shell + kubectl apply -f upgrade_v1alpha1_os.yaml + ``` * 回退至上一版本 + * OS回退至上一版本：修改upgrade_v1alpha1_os.yaml，设置osversion为上一版本，opstype为rollback，回退至上一版本（即切换至上一分区）。YAML示例如下： - * 修改upgrade_v1alpha1_os.yaml，设置osversion为上一版本，opstype为rollback，回退至上一版本（即切换至上一分区）。YAML示例如下： - - ``` + ```yaml + apiVersion: upgrade.openeuler.org/v1alpha1 + kind: OS + metadata: + name: os-sample + spec: + imagetype: "" + opstype: rollback + osversion: KubeOS pervious version + maxunavailable: 2 + containerimage: "" + evictpodforce: true/false + imageurl: "" + checksum: "" + flagSafe: false + mtls: true + ``` + + * 配置回退至上一版本：修改upgrade_v1alpha1_os.yaml，设置sysconfigs/upgradeconfigs的version为上一版本，回退至上一版本（已配置的参数无法回退）。YAML示例如下： + + ```yaml apiVersion: upgrade.openeuler.org/v1alpha1 kind: OS metadata: name: os-sample spec: imagetype: "" - opstype: rollback - osversion: KubeOS pervious version - maxunavailable: 2 - dockerimage: "" + opstype: config + osversion: edit.os.version + maxunavailable: edit.node.config.number + containerimage: "" + evictpodforce: true/false imageurl: "" checksum: "" flagSafe: false - mtls:true + mtls: false + sysconfigs: + version: previous config version + configs: + - model: kernel.sysctl + contents: + - key: kernel param key1 + value: kernel param value1 + - key: kernel param key2 + value: kernel param value2 + - model: kernel.sysctl.persist + configpath: persist file path + contents: + - key: kernel param key3 + value: kernel param value3 ``` - * YAML修改完成后执行更新命令，在集群中更新定制对象后，节点会根据配置的字段信息进行回退 +* YAML修改完成后执行更新命令，在集群中更新定制对象后，节点会根据配置的字段信息进行回退。 - ``` - kubectl apply -f upgrade_v1alpha1_os.yaml + ```shell + kubectl apply -f upgrade_v1alpha1_os.yaml + ``` + + 更新完成后，节点会根据配置信息回退容器 OS。 +* 查看节点容器 OS 版本(回退OS版本)或节点config版本&节点状态为idle(回退config版本)，确认回退是否成功。 + + ```shell + kubectl get osinstances -o custom-columns='NAME:.metadata.name,NODESTATUS:.spec.nodestatus,SYSCONFIG:status.sysconfigs.version,UPGRADECONFIG:status.upgradeconfigs.version' + ``` + +## 附录 + +### Setting 列表 + +#### kernel Settings + +* kenerl.sysctl：临时设置内核参数，重启后无效，key/value 表示内核参数的 key/value， key与value均不能为空且key不能包含“=”，该参数不支持删除操作（operation=delete）示例如下: + + ```yaml + configs: + - model: kernel.sysctl + contents: + - key: user.max_user_namespaces + value: 16384 + - key: net.ipv4.tcp_tw_recycle + value: 0 + operation: delete + ``` + +* kernel.sysctl.persist: 设置持久化内核参数，key/value表示内核参数的key/value，key与value均不能为空且key不能包含“=”， configpath为配置文件路径，支持新建（需保证父目录存在），如不指定configpath默认修改/etc/sysctl.conf，示例如下： + ```yaml + configs: + - model: kernel.sysctl.persist + configpath : /etc/persist.conf + contents: + - key: user.max_user_namespaces + value: 16384 + - key: net.ipv4.tcp_tw_recycle + value: 0 + operation: delete ``` - 更新完成后，节点会根据配置信息回退容器 OS。 +#### Grub Settings + +* grub.cmdline.current/next: 设置grub.cfg文件中的内核引导参数，该行参数在grub.cfg文件中类似如下示例： -* 查看节点容器 OS 版本，确认回退是否成功。 + ```shell + linux /boot/vmlinuz root=/dev/sda2 ro rootfstype=ext4 nomodeset quiet oops=panic softlockup_panic=1 nmi_watchdog=1 rd.shell=0 selinux=0 crashkernel=256M panic=3 + ``` + + * 在dm-verity模式下，grub.cmdline配置下发无效。 + + * KubeOS使用双分区，grub.cmdline.current/next支持对当前分区或下一分区进行配置： + + * grub.cmdline.current：对当前分区的启动项参数进行配置。 + * grub.cmdline.next：对下一分区的启动项参数进行配置。 + + * 注意：升级/回退前后的配置，始终基于升级/回退操作下发时的分区位置进行current/next的区分。假设当前分区为A分区，下发升级操作并在sysconfigs（升级重启后配置）中配置grub.cmdline.current，重启后进行配置时仍修改A分区对应的grub cmdline。 + + * grub.cmdline.current/next支持“key=value”（value不能为空），也支持单key。若value中有“=”，例如“root=UUID=some-uuid”，key应设置为第一个“=”前的所有字符，value为第一个“=”后的所有字符。 配置方法示例如下： + + ```yaml + configs: + - model: grub.cmdline.current + contents: + - key: selinux + value: "0" + - key: root + value: UUID=e4f1b0a0-590e-4c5f-9d8a-3a2c7b8e2d94 + - key: panic + value: "3" + operation: delete + - key: crash_kexec_post_notifiers + - model: grub.cmdline.next + contents: + - key: selinux + value: "0" + - key: root + value: UUID=e4f1b0a0-590e-4c5f-9d8a-3a2c7b8e2d94 + - key: panic + value: "3" + operation: delete + - key: crash_kexec_post_notifiers + ``` +#### kubelet配置 + +* kuberntes.kubelet: 配置节点kubelet的配置文件中的参数，参数说明和约束如下： + * 仅支持```KubeletConfiguration```中的配置参数。 + * 节点kubelet配置文件需要为yaml格式的文件。 + * 如不指定configpath，默认配置文件路径为```/var/lib/kubelet/config.yaml```，并且需要注意的是配置文件的路径需要与kubelet启动时的```-- config```参数指定的路径一致才能生效，用户需保证配置文件路径有效。 + * kubelet配置的value参数类型支持为空/null、int、float、string、boolean和数组。当为数组时，数组元素允许重复，数组参数进行更新时会追加到已有数组中。如需修改数组中的元素，需要先删除数组，再新增数组来完成修改。 + * 如配置存在嵌套，则通过```'.'```连接嵌套的key值，例如如果修改如下yaml示例中```cacheAuthorizedTTL```参数为1s。 + + ```yaml + authorization: + mode: Webhook + webhook: + cacheAuthorizedTTL: 0s ``` - kubectl get nodes -o custom-columns='NAME:.metadata.name,OS:.status.nodeInfo.osImage' + 参数配置示例如下： + ```yaml + configs: + - model: kuberntes.kubelet + configpath: /etc/test.yaml + contents: + - key: authorization.webhook.cacheAuthorizedTTL + value: 1s ``` + * kubernetes.kubelet进行删除时，不对value与配置文件中的值进行比较。 +#### containerd配置 + +* container.containerd: 配置节点上containerd的配置文件中的参数，参数说明和约束如下： + * containerd需要配置文件为toml格式，所以key为toml中该参数的表头.键名，例如希望修改如下toml示例中```no_shim```为true。 + ```toml + [plugins."io.containerd.runtime.v1.linux"] + no_shim=false + runtime="runc" + runtime_root=" + ``` + 参数配置示例如下： + ```yaml + configs: + - model: container.containerd + configpath: /etc/test.toml + contents: + - key: plugins."io.containerd.runtime.v1.linux".no_shim + value: true + ``` + * toml使用```.```分割键，os-agent识别时与toml保持一致，所以当键名中包含```.```时，该键名需要使用```""```，例如上例中的```"io.containerd.runtime.v1.linux"```为一个键 + * 如不指定configpath，默认配置文件路径为```/etc/containerd/config.toml```，用户需要保证配置文件路径有效。 + * container.conatainerd配置的key和value均不能为空，value参数类型支持int、float、string、boolean和数组。当为数组时，数组元素允许重复，数组参数进行更新时会追加到已有数组中。如需修改数组中的元素，需要先删除数组，再新增数组来完成修改。 + * container.containerd进行删除时，不对value与配置文件中的值进行比较。 + +#### Pam Limits配置 + +* pam.limits：配置节点上/etc/security/limits.conf文件 + * key为domain值，value的格式需要为type.item.value（limits.conf文件要求每行格式为：\
+**修改name为主机名，与环境配置[第一步](#1-设置主机名)一致：** +
+ +
+**将advertiseAddress修改为控制平面的ip地址：** +
+ +
+**在Networking中添加podSubnet指定CIDR范围：** +
+ + +### 2. 部署集群 +这里使用kubeadm部署集群，许多配置是默认生成的（如认证证书），如需修改请查阅[官方文档](https://kubernetes.io/zh-cn/docs/home/ )。 + +**关闭代理（如有）：** +``` +$ unset http_proxy https_proxy +``` +使用kubeadm init部署集群： + +``` +$ kubeadm init --config kubeletConfig.yaml +``` +指定kubectl使用的配置文件： +``` +$ mkdir -p "$HOME"/.kube +$ cp -i /etc/kubernetes/admin.conf "$HOME"/.kube/config +$ chown "$(id -u)":"$(id -g)" "$HOME"/.kube/config +$ export KUBECONFIG=/etc/kubernetes/admin.conf +``` +### 3. 部署cni插件（flannel） +本教程中使用flannel作为cni插件，以下介绍flannel下载和部署。 +以下使用的flannel从registry-1.docker.io镜像源下载，为避免证书验证失败的问题，请在containerd配置文件（/etc/containerd/config.toml）中配置该镜像源跳过证书验证。 +
+ +
+使用kubectl apply部署最开始在软件包安装中下载的kube-flannel.yml。 +``` +$ kubectl apply -f kube-flannel.yml +``` +> **说明** +> +> 控制平面可能会有污点的问题，导致kubectl get nodes中节点状态无法变成ready，请查阅[官方文档](https://kubernetes.io/zh-cn/docs/concepts/scheduling-eviction/taint-and-toleration/)去除污点。 +## 加入集群（仅工作节点需要） +**关闭代理（如有）：** +``` +$ unset http_proxy https_proxy +``` +工作节点安装配置完环境后可以通过以下命令加入集群。 + +``` +$ kubeadm join
+**在工作节点运行kubectl命令（可选）：** + +如果需要在工作节点上运行kubectl命令，需要将控制面板的配置文件/etc/kubernetes/admin.conf复制到同样的目录，然后运行以下命令进行配置： + +``` +$ export KUBECONFIG=/etc/kubernetes/admin.conf +``` \ No newline at end of file diff --git "a/docs/zh/docs/Kubernetes/eggo\351\203\250\347\275\262\351\233\206\347\276\244.md" "b/docs/zh/docs/Kubernetes/eggo\351\203\250\347\275\262\351\233\206\347\276\244.md" index deac5b80cb22f740bcf7d9999b7fb683b2dfbfdc..4ee2bb86b74e2f25b4babe42d1b0c20f19bd9287 100644 --- "a/docs/zh/docs/Kubernetes/eggo\351\203\250\347\275\262\351\233\206\347\276\244.md" +++ "b/docs/zh/docs/Kubernetes/eggo\351\203\250\347\275\262\351\233\206\347\276\244.md" @@ -192,7 +192,7 @@ $ eggo template -f template.yaml 或者直接使用命令行方式修改默认配置，参考命令如下： ```shell -$ eggo template -f template.yaml -n k8s-cluster -u username -p password --masters 192.168.0.1 --masters 192.168.0.2 --workers 192.168.0.3 --etcds 192.168.0.4 --loadbalancer 192.168.0.5 +$ eggo template -f template.yaml -n k8s-cluster -u username -p password --masters 192.168.0.1 --masters 192.168.0.2 --workers 192.168.0.3 --etcds 192.168.0.4 --loadbalance 192.168.0.5 ``` ## 安装 Kubernetes 集群 diff --git a/docs/zh/docs/Kubernetes/figures/advertiseAddress.png b/docs/zh/docs/Kubernetes/figures/advertiseAddress.png new file mode 100644 index 0000000000000000000000000000000000000000..b36e5c4664f2d2e5faaa23128fd4711c11e30179 Binary files /dev/null and b/docs/zh/docs/Kubernetes/figures/advertiseAddress.png differ diff --git a/docs/zh/docs/Kubernetes/figures/flannelConfig.png b/docs/zh/docs/Kubernetes/figures/flannelConfig.png new file mode 100644 index 0000000000000000000000000000000000000000..dc9e7c665edd02fad16d3e6f4970e3125efcbef8 Binary files /dev/null and b/docs/zh/docs/Kubernetes/figures/flannelConfig.png differ diff --git a/docs/zh/docs/Kubernetes/figures/name.png b/docs/zh/docs/Kubernetes/figures/name.png new file mode 100644 index 0000000000000000000000000000000000000000..dd6ddfdc3476780e8c896bfd5095025507f62fa8 Binary files /dev/null and b/docs/zh/docs/Kubernetes/figures/name.png differ diff --git a/docs/zh/docs/Kubernetes/figures/podSubnet.png b/docs/zh/docs/Kubernetes/figures/podSubnet.png new file mode 100644 index 0000000000000000000000000000000000000000..b368f77dd7dfd7722dcf7751b3e37ec28755e42d Binary files /dev/null and b/docs/zh/docs/Kubernetes/figures/podSubnet.png differ diff --git "a/docs/zh/docs/Kubernetes/\345\207\206\345\244\207\350\257\201\344\271\246.md" "b/docs/zh/docs/Kubernetes/\345\207\206\345\244\207\350\257\201\344\271\246.md" index a355988d398e7da8ad77692bb47ce2691af2920c..63b4a973ad35351fb770cf1e051b80cc9de25db3 100644 --- "a/docs/zh/docs/Kubernetes/\345\207\206\345\244\207\350\257\201\344\271\246.md" +++ "b/docs/zh/docs/Kubernetes/\345\207\206\345\244\207\350\257\201\344\271\246.md" @@ -6,6 +6,28 @@ 部署集群前，需要生成集群各组件之间通信所需的证书。本文使用开源 CFSSL 作为验证部署工具，以便用户了解证书的配置和集群组件之间证书的关联关系。用户可以根据实际情况选择合适的工具，例如 OpenSSL 。 +## 配置go环境 + +1. 下载go +``` +wget https://go.dev/dl/go1.22.3.linux-amd64.tar.gz +``` + +2. 移除旧版本并安装 +``` +$ rm -rf /usr/local/go && tar -C /usr/local -xzf go1.22.3.linux-amd64.tar.gz +``` + +3. 添加环境变量 +``` +export PATH=$PATH:/usr/local/go/bin +``` + +4. 检查是否安装成功 +``` +go version +``` + ## 编译安装 CFSSL 编译安装 CFSSL 的参考命令如下（需要互联网下载权限，需要配置代理的请先完成配置，需要配置 go语言环境）: diff --git "a/docs/zh/docs/Kubernetes/\345\256\211\350\243\205Kubernetes\350\275\257\344\273\266\345\214\205.md" "b/docs/zh/docs/Kubernetes/\345\256\211\350\243\205Kubernetes\350\275\257\344\273\266\345\214\205.md" index 98fc9552e3d9d5fe80981ee9bf43d42f2d6cfba4..924795f889b5bf8747baed8d21904f1dda27aba9 100644 --- "a/docs/zh/docs/Kubernetes/\345\256\211\350\243\205Kubernetes\350\275\257\344\273\266\345\214\205.md" +++ "b/docs/zh/docs/Kubernetes/\345\256\211\350\243\205Kubernetes\350\275\257\344\273\266\345\214\205.md" @@ -1,13 +1,11 @@ # 安装 Kubernetes 软件包 - ```bash -$ dnf install -y docker conntrack-tools socat +dnf install -y docker conntrack-tools socat ``` 配置EPOL源之后，可以直接通过 dnf 安装 K8S ```bash -$ rpm -ivh kubernetes*.rpm +dnf install kubernetes ``` - diff --git "a/docs/zh/docs/LLM/llama.cpp\344\275\277\347\224\250\346\214\207\345\215\227.md" "b/docs/zh/docs/LLM/llama.cpp\344\275\277\347\224\250\346\214\207\345\215\227.md" index 68d2ccc039b0d4ebf8e188cc5dcf47949cab96b5..609af9b39f59602c5ccd3dc9a151595287cecc7c 100644 --- "a/docs/zh/docs/LLM/llama.cpp\344\275\277\347\224\250\346\214\207\345\215\227.md" +++ "b/docs/zh/docs/LLM/llama.cpp\344\275\277\347\224\250\346\214\207\345\215\227.md" @@ -15,7 +15,7 @@ llama.cpp 核心架构分为两层： 特性： -- 基于 ggml的C/C++ 实现 +- 基于 ggml的C/C++ 实现； - 通过 int4/int8 量化、优化的KV缓存和并行计算等多种方式加速 CPU 推理； - 互动界面是流媒体生成，具有打字机效果； - 无需 GPU，可只用 CPU 运行。 diff --git "a/docs/zh/docs/NestOS/NestOS For Container\347\224\250\346\210\267\346\214\207\345\215\227.md" "b/docs/zh/docs/NestOS/NestOS For Container\347\224\250\346\210\267\346\214\207\345\215\227.md" new file mode 100644 index 0000000000000000000000000000000000000000..47385becf24cb21b9eda03ae665920b02e990079 --- /dev/null +++ "b/docs/zh/docs/NestOS/NestOS For Container\347\224\250\346\210\267\346\214\207\345\215\227.md" @@ -0,0 +1,995 @@ +# NestOS用户使用指南 + +## 1. NestOS介绍 + +### 1.1 前言 + +NestOS是麒麟软件在openEuler社区开源孵化的云底座操作系统，集成了rpm-ostree支持、ignition配置等技术，采用双根文件系统互为主备、原子化更新的设计思路，提供nestos-assembler工具快速集成构建。NestOS针对K8S、OpenStack平台进行适配，优化容器运行底噪，使系统具备十分便捷的集群组建能力，可以更安全的运行大规模的容器化工作负载。 + +本手册将完整阐述从构建、安装部署到使用NestOS的全流程，帮助用户充分利用NestOS的优势，快速高效地完成系统的配置和部署。 + +### 1.2 应用场景与优势 + +NestOS 适合作为以容器化应用为主的云场景基础运行环境，解决了在使用容器技术与容器编排技术实现业务发布、运维时与底层环境高度解耦而带来的运维技术栈不统一，运维平台重复建设等问题，保证了业务与底座操作系统运维的一致性。 + + + +## 2. 环境准备 + +### 2.1 构建环境要求 + +#### 2.1.1 制作构建工具nestos-assembler环境要求 + +- 推荐使用openEuler环境 + +- 剩余可用硬盘空间 > 5G + +#### 2.1.2 构建NestOS环境要求 + +| **类别** | **要求** | +| :------: | :---------------: | +| CPU | 4vcpu | +| 内存 | 4GB | +| 硬盘 | 剩余可用空间>10GB | +| 架构 | x86_64或aarch64 | +| 其他 | 支持kvm | + +### 2.2 部署配置要求 + +| **类别** | **推荐配置** | **最低配置** | +| :------: | :-------------: | :----------: | +| CPU | >4vcpu | 1vcpu | +| 内存 | >4GB | 512M | +| 硬盘 | >20GB | 10GB | +| 架构 | x86_64、aarch64 | / | + +## 3. 快速使用 + +### 3.1 快速构建 + +1）获取nestos-assembler容器镜像 + +推荐使用基于openEuler的base镜像，更多说明请参考6.1 + +``` +docker pull hub.oepkgs.net/nestos/nestos-assembler:24.03-LTS.20240903.0-aarch64 +``` + +2）编写名为nosa的脚本并存放至/usr/local/bin，并赋予可执行权限 + +``` +#!/bin/bash + +sudo docker run --rm -it --security-opt label=disable --privileged --user=root \ + -v ${PWD}:/srv/ --device /dev/kvm --device /dev/fuse --network=host \ + --tmpfs /tmp -v /var/tmp:/var/tmp -v /root/.ssh/:/root/.ssh/ -v /etc/pki/ca-trust/:/etc/pki/ca-trust/ \ + ${COREOS_ASSEMBLER_CONFIG_GIT:+-v $COREOS_ASSEMBLER_CONFIG_GIT:/srv/src/config/:ro} \ + ${COREOS_ASSEMBLER_GIT:+-v $COREOS_ASSEMBLER_GIT/src/:/usr/lib/coreos-assembler/:ro} \ + ${COREOS_ASSEMBLER_CONTAINER_RUNTIME_ARGS} \ + ${COREOS_ASSEMBLER_CONTAINER:-nestos-assembler:your_tag} "$@" +``` + +注意修改COREOS_ASSEMBLER_CONTAINER 的值为本地环境中实际的nestos-assembler容器镜像。 + +3）获取nestos-config + +使用nosa init 初始化构建工作目录，拉取构建配置，创建工作目录nestos-build，在该目录下执行如下命令 + +``` +nosa init https://gitee.com/openeuler/nestos-config +``` + +4）调整构建配置 + +nestos-config提供默认构建配置，无需额外操作。如需调整，请参考第5章。 + +5）NestOS镜像构建 + +``` +# 拉取构建配置、更新缓存 +nosa fetch +# 生成根文件系统、qcow2及OCI镜像 +nosa build +# 生成live iso及PXE镜像 +nosa buildextend-metal +nosa buildextend-metal4k +nosa buildextend-live +``` + +详细构建及部署流程请参考第6章。 + +### 3.2 快速部署 + +以NestOS ISO镜像为例，启动进入live环境后，执行如下命令根据向导提示完成安装： + +``` +sudo installnestos +``` + +其他部署方式请参考第8章。 + +## 4. 系统默认配置 + +| **选项** | **默认配置** | +| :-------------: | :---------------------: | +| docker服务 | 默认disable，需主动开启 | +| ssh服务安全策略 | 默认仅支持密钥登录 | + +## 5. 构建配置nestos-config + +### 5.1 获取配置 + +nestos-config的仓库地址为https://gitee.com/openeuler/nestos-config + +### 5.2 配置目录结构说明 + +| **目录/****文件** | **说明** | +| :---------------: | :--------------------: | +| live/* | 构建liveiso的引导配置 | +| overlay.d/* | 自定义文件配置 | +| tests/* | 用户自定义测试用例配置 | +| *.repo | repo源配置 | +| .yaml，manifests/ | 主要构建配置 | + +### 5.3 主要文件解释 + +#### 5.3.1 repo文件 + +目录下的repo文件可用来配置用于构建nestos的软件仓库。 + +#### 5.3.2 yaml配置文件 + +目录下的yaml文件主要是提供nestos构建的各种配置，详见5.4章节。 + +### 5.4 主要字段解释 + +| **字段名称** | **作用** | +| :------------------------------------------ | ------------------------------------------------------------ | +| packages-aarch64、packages-x86_64、packages | 软件包集成范围 | +| exclude-packages | 软件包集成黑名单 | +| remove-from-packages | 从指定软件包删除文件(夹) | +| remove-files | 删除特定文件(夹) | +| extra-kargs | 额外内核引导参数 | +| initramfs-args | initramfs构建参数 | +| postprocess | 文件系统构建后置脚本 | +| default-target | 配置default-target，如 multi-user.target | +| rolij.name、releasever | 镜像相关信息(镜像名称、版本) | +| lockfile-repos | 构建可使用的仓库名列表,与5.3.1 介绍的repo文件中的仓库名需要对应 | + +### 5.5 用户可配置项说明 + +#### 5.5.1 repo源配置 + +1）在配置目录编辑repo文件，将内容修改为期望的软件仓库 + +``` +$ vim nestos-pool.repo +[repo_name_1] +Name=xxx +baseurl = https://ip.address/1 +enabled = 1 + +[repo_name_2] +Name=xxx +baseurl = https://ip.address/2 +enabled = 1 +``` + +2）修改yaml配置文件中的lockfile-repo字段内容为相应的仓库名称列表 + +注：仓库名称为repo文件中[]内的内容，不是name字段内容 + +``` +$ vim manifests/rpmlist.yaml +修改lockfile-repo字段内容为 +lockfile-repos: +- repo_name_1 +- repo_name_2 +``` + +#### 5.5.2 软件包裁剪 + +修改packages、packages-aarch64、packages-x86_64字段，可在其中添加或删除软件包。 + +如下所示，在package字段中添加了nano，构建安装后系统中会有nano 。 + +``` +$ vim manifests/rpmlist.yaml +packages: +- bootupd +... +- authselect +- nano +... +packages-aarch64: +- grub2-efi-aa64 +packages-x86_64: +- microcode_ctl +- grub2-efi-x64 +``` + +#### 5.5.3 自定义镜像名称与版本号 + +修改yaml文件中的releasever及rolij.name 字段，这些字段分别控制镜像的版本号及名称。 + +``` +$ vim manifest.yaml + +releasever: "1.0" +rojig: + license: MIT + name: nestos + summary: NestOS stable +``` + +如上配置，构建出的镜像格式为：nestos-1.0.$(date "+%Y%m%d").$build_num.$type，其中build_num为构建次数，type为类型后缀。 + +#### 5.5.4 自定义镜像中的release信息 + +正常release信息是由我们集成的release包（如openeuler-release）提供的，但是我们也可以通过添加postprocess脚本对/etc/os-release文件进行重写操作。 + +``` +$ vim manifests/ system-configuration.yaml +在postprocess添加如下内容，若已存在相关内容，则只需修改对应release信息即可 +postprocess: + - | + #!/usr/bin/env bash + set -xeuo pipefail + export OSTREE_VERSION="$(tail -1 /etc/os-release)" + date_now=$(date "+%Y%m%d") + echo -e 'NAME="openEuler NestOS"\nVERSION="24.03-LTS"\nID="openeuler"\nVERSION_ID="24.03-LTS"\nPRETTY_NAME="NestOS"\nANSI_COLOR="0;31"\nBUILDID="'${date_now}'"\nVARIANT="NestOS"\nVARIANT_ID="nestos"\n' > /usr/lib/os-release + echo -e $OSTREE_VERSION >> /usr/lib/os-release + cp -f /usr/lib/os-release /etc/os-release +``` + +#### 5.5.5 成自定义文件 + +在overlay.d目录下每个目录进行自定义文件的添加和修改，这种操作可以实现构建镜像内容的自定义。 + +``` +mkdir -p overlay.d/15nestos/etc/test/test.txt +echo "This is a test message !" > overlay.d/15nestos/etc/test/test.txt +``` + +使用如上配置进行镜像构建，启动构建出的镜像，查看系统中对应文件内容即为我们上述自定义添加的内容。 + +``` +[root@nosa-devsh ~]# cat /etc/test/test.txt +This is a test message ! +``` + +## 6.构建流程 + +NestOS采用容器化的方式将构建工具链集成为一个完整的容器镜像，称为NestOS-assembler。 + +NestOS提供构建NestOS-assembler容器镜像能力，方便用户使用。使用该容器镜像，用户可在任意linux发行版环境中构建多种形态NestOS镜像（例如在现有CICD环境中使用），也可对构建发布件进行管理、调试和自动化测试。 + +### 6.1 制作构建工具NestOS-assembler容器镜像 + +#### 6.1.1 前置步骤 + +1）准备容器base镜像 + +NestOS-assembler容器镜像需要基于支持yum/dnf软件包管理器的base镜像制作，理论上可由任意发行版base镜像制作，但为最大程度减少软件包兼容性问题，仍推荐使用基于openEuler的base镜像。 + +2）安装必要软件包 + +安装必备依赖docker + +``` +dnf install -y docker +``` + +3）克隆nestos-assembler源代码仓库 + +``` +git clone --depth=1 --single-branch https://gitee.com/openeuler/nestos-assembler.git +``` + +#### 6.1.2 构建NestOS-assembler容器镜像 + +使用openEuler容器镜像作为base镜像，使用以下指令构建： + +``` +cd nestos-assembler/ +docker build -f Dockerfile . -t nestos-assembler:your_tag +``` + +### 6.2 使用NestOS-assembler容器镜像 + +#### 6.2.1 前置步骤 + +1）准备nestos-assembler容器镜像 + +参考6.1章节构建nestos-assembler容器镜像后，可通过私有化部署容器镜像仓库对该容器镜像进行管理和分发。请确保构建NestOS前，拉取适当版本的nestos-assembler容器镜像至当前环境。 + +2）编写使用脚本nosa + +因NestOS构建过程需多次调用nestos-assembler容器镜像执行不同命令，同时需配置较多参数，为简化用户操作，可编写nosa命令脚本，可参见3.1快速构建部分。 + +#### 6.2.2 使用说明 + +构建工具命令一览 + +| **命令** | **功能说明** | +| :-------------------: | :-------------------------------------------------: | +| init | 初始化构建环境及构建配置，详见6.3 | +| fetch | 根据构建配置获取最新软件包至本地缓存 | +| build | 构建ostree commit，是构建NestOS的核心命令 | +| run | 直接启动一个qemu实例，默认使用最新构建版本 | +| prune | 清理历史构建版本，默认保留最新3个版本 | +| clean | 删除全部构建发布件，添加--all参数时同步清理本地缓存 | +| list | 列出当前构建环境中存在的版本及发布件 | +| build-fast | 基于前次构建记录快速构建新版本 | +| push-container | 推送容器镜像发布件至容器镜像仓库 | +| buildextend-live | 构建支持live环境的ISO发布件及PXE镜像 | +| buildextend-metal | 构建裸金属raw发布件 | +| buildextend-metal4k | 构建原生4K模式的裸金属raw发布件 | +| buildextend-openstack | 构建适用于openstack平台的qcow2发布件 | +| buildextend-qemu | 构建适用于qemu的qcow2发布件 | +| basearch | 获得当前架构信息 | +| compress | 压缩发布件 | +| kola | 自动化测试框架 | +| kola-run | 输出汇总结果的自动化测试封装 | +| runc | 以容器方式挂载当前构建根文件系统 | +| tag | 管理构建工程tag | +| virt-install | 通过virt-install为指定构建版本创建实例 | +| meta | 管理构建工程元数据 | +| shell | 进入nestos-assembler容器镜像 | + +### 6.3 准备构建环境 + +NestOS构建环境需要独立的空文件夹作为工作目录，且支持多次构建，保留、管理历史构建版本。创建构建环境前需首先准备构建配置（参考第5章）。 + +建议一份独立维护的构建配置对应一个独立的构建环境，即如果您希望构建多个不同用途的NestOS，建议同时维护多份构建配置及对应的构建环境目录，这样可以保持不同用途的构建配置独立演进和较为清晰的版本管理。 + +#### 6.3.1 初始化构建环境 + +进入待初始化工作目录，执行如下命令即可初始化构建环境： + +``` +nosa init https://gitee.com/openeuler/nestos-config +``` + +仅首次构建时需初始化构建环境，后续构建在不对构建配置做出重大更改的前提下，可重复使用该构建环境。 + +#### 6.3.2 构建环境说明 + +初始化完成后，工作目录创建出如下文件夹： + +**builds:**构建发布件及元数据存储目录，latest子目录软链接指向最新构建版本。 + +**cache:**缓存目录，根据构建配置中的软件源及软件包列表拉取至本地，历史构建NestOS的ostree repo均缓存于此目录。 + +**overrides:**构建过程希望附加到最终发布件rootfs中的文件或rpm包可置于此目录。 + +**src:**构建配置目录，存放nestos-config相关内容。 + +**tmp:**临时目录，构建过程、自动化测试等场景均会使用该目录作为临时目录，构建发生异常时可在此处查看虚拟机命令行输出、journal日志等信息。 + +### 6.4 构建步骤 + +NestOS构建主要步骤及参考命令如下： + + + +#### 6.4.1 首次构建 + +首次构建时需初始化构建环境，详见6.3。 + +非首次构建可直接使用原构建环境，可通过nosa list查看当前构建环境已存在版本及对应发布件。 + +#### 6.4.2 更新构建配置及缓存 + +初始化构建环境后，执行如下命令更新构建配置及缓存： + +``` +nosa fetch +``` + +该步骤初步校验构建配置是否可用，并通过配置的软件源拉取软件包至本地缓存。当构建配置发生变更或单纯希望更新软件源中最新版本软件包，均需要重新执行该步骤，否则可能导致构建失败或不符合预期。 + +当构建配置发生较大变更，希望清空本地缓存重新拉取时，需执行如下命令： + +``` +nosa clean --all +``` + +#### 6.4.3 构建不可变根文件系统 + +NestOS不可变操作系统的核心是基于ostree技术的不可变根文件系统，执行如下步骤构建ostree文件系统： + +``` +nosa build +``` + +build命令默认会生成ostree文件系统和OCI归档文件，您也可以在执行命令时同步添加qemu、metal、metal4k中的一个或多个，同步构建发布件，等效于后续继续执行buildextend-qemu、buildextend-metal和buildextend-metal4k命令。 + +``` +nosa build qemu metal metal4k +``` + +如您希望在构建NestOS时，添加自定义文件或rpm包，请在执行build命令前将相应文件放入构建环境overrides目录下rootfs/或rpm/文件夹。 + +#### 6.4.4 构建各类发布件 + +build命令执行完毕后，可继续执行buildextend-XXX命令用于构建各类型发布件，具体介绍如下： + +- 构建qcow2镜像 + +``` +nosa buildextend-qemu +``` + +- 构建带live环境的ISO镜像或PXE启动组件 + +``` +nosa buildextend-metal +nosa buildextend-metal4k +nosa buildextend-live +``` + +- 构建适用于openstack环境的qcow2镜像 + +``` +nosa buildextend-openstack +``` + +- 构建适用于容器镜像方式更新的容器镜像 + +执行nosa build命令构建ostree文件系统时，会同时生成ociarchive格式镜像，该镜像可直接执行如下命令推送到本地或远程镜像仓库，无需执行其他构建步骤。 + +``` +nosa push-container [container-image-name] +``` + + 远程镜像仓库地址需附加到推送容器镜像名称中，且除隔离镜像tag外，不得出现":"。如未检测到":"，该命令会自动生成{latest_build}-{arch}格式的tag。示例如下： + +``` +nosa push-container registry.example.com/nestos:1.0.20240903.0-x86_64 +``` + +该命令支持以下可选参数： + +--authfile ：指定登录远程镜像仓库的鉴权文件 + +--insecure：如远程镜像仓库采用自签名证书等场景，添加该参数可不校验SSL/TLS协议 + +--transport：指定目标镜像推送协议，默认为docker，具体支持项及说明如下： + + containers-storage：推送至podman、crio等容器引擎本地存储目录 + + dir：推送至指定本地目录 + + docker：以docker API推送至私有或远端容器镜像仓库 + + docker-archive：等效于docker save导出归档文件，可供docker load使用 + + docker-daemon：推送至docker容器引擎本地存储目录 + +### 6.5 获取发布件 + +构建完毕后，发布件均生成于构建环境中如下路径： + +``` +builds/{version}/{arch}/ +``` + +如您仅关心最新构建版本或通过CI/CD调用，提供latest目录软链接至最新版本目录，即： + +``` +builds/latest/{arch}/ +``` + +为方便传输，您可以调用如下命令，压缩发布件体积： + +``` +nosa compress +``` + +压缩后原文件会被移除，会导致部分调试命令无法使用，可以调用解压命令恢复原文件： + +``` +nosa uncompress +``` + +### 6.6 构建环境维护 + +在构建NestOS环境前后，可能存在如下需求，可使用推荐的命令解决相应问题： + +#### 6.6.1 清理历史或无效构建版本，以释放磁盘空间 + +可以通过以下命令清理历史版本构建： + +``` +nosa prune +``` + +也可删除当前构建环境中的全部发布件： + +``` +nosa clean +``` + +如构建配置更换过软件源或历史缓存无保留价值，可彻底清理当前构建环境缓存： + +``` +nosa clean --all +``` + +#### 6.6.2 临时运行构建版本实例，用于调试或确认构建正确 + +``` +nosa run +``` + +可通过--qemu-image或--qemu-iso指定启动镜像地址，其余参数请参考nosa run --help说明。 + +实例启动后，构建环境目录会被挂载至/var/mnt/workdir，可通过构建环境目录 + +#### 6.6.3 运行自动化测试 + +``` +nosa kola run +``` + +该命令会执行预设的测试用例，也可在其后追加测试用例名称，单独执行单条用例。 + +``` +nosa kola testiso +``` + +该命令会执行iso或pxe live环境安装部署测试，可作为构建工程的冒烟测试。 + +#### 6.6.4 调试验证构建工具（NestOS-assembler） + +``` +nosa shell +``` + +该命令可启动进入构建工具链容器的shell环境，您可以通过此命令验证构建工具链工作环境是否正常。 + +## 7. 部署配置 + +### 7.1 前言 + +在开始部署NestOS之前，了解和准备必要的配置是至关重要的。NestOS通过点火文件（ignition文件）提供了一系列灵活的配置选项，可以通过Butane工具进行管理，方便用户进行自动化部署和环境设置。 + +在本章节中，将详细的介绍Butane工具的功能和使用方法，并根据不同场景提供配置示例。这些配置将帮助您快速启动和运行NestOS，在满足应用需求的同时，确保系统的安全性和可靠性。此外，还会介绍如何自定义镜像，将点火文件预集成至镜像中，以满足特定应用场景的需求，从而实现高效的配置和部署NestOS。 + +### 7.2 Butane简介 + +Butane是一个用于将人类可读的YAML配置文件转换为NestOS点火文件（Ignition 文件）的工具。Butane工具简化了复杂配置的编写过程，允许用户以更易读的格式编写配置文件，然后将其转换为适合NestOS使用的JSON格式。 + +NestOS对Butane进行了适配修改，新增nestos变体支持和配置规范版本v1.0.0，对应的点火（ignition）配置规范为v3.3.0，确保了配置的稳定性和兼容性。 + +### 7.3 Butane使用 + +安装butane软件包 + +``` +dnf install butane +``` + +编辑example.yaml并执行以下指令将其转换为点火文件example.ign，其中关于yaml文件的编写，将在后续展开： + +``` +butane example.yaml -o example.ign -p +``` + +### 7.4 支持的功能场景 + +以下配置示例（example.yaml）简述了NestOS主要支持的功能场景和进阶使用方法。 + +#### 7.4.1 设置用户和组并配置密码/密钥 + +``` +variant: nestos +version: 1.0.0 +passwd: + users: + - name: nest + ssh_authorized_keys: + - ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDHn2eh... + - name: jlebon + groups: + - wheel + ssh_authorized_keys: + - ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQDC5QFS... + - ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIIveEaMRW... + - name: miabbott + groups: + - docker + - wheel + password_hash: $y$j9T$aUmgEDoFIDPhGxEe2FUjc/$C5A... + ssh_authorized_keys: + - ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAACAQDTey7R... +``` + +#### 7.4.2 文件操作——以配置网卡为例 + +``` +variant: nestos +version: 1.0.0 +storage: + files: + - path: /etc/NetworkManager/system-connections/ens2.nmconnection + mode: 0600 + contents: + inline: | + [connection] + id=ens2 + type=ethernet + interface-name=ens2 + [ipv4] + address1=10.10.10.10/24,10.10.10.1 + dns=8.8.8.8; + dns-search= + may-fail=false + method=manual +``` + +#### 7.4.3 创建目录、文件、软连接并配置权限 + +``` +variant: nestos +version: 1.0.0 +storage: + directories: + - path: /opt/tools + overwrite: true + files: + - path: /var/helloworld + overwrite: true + contents: + inline: Hello, world! + mode: 0644 + user: + name: dnsmasq + group: + name: dnsmasq + - path: /opt/tools/transmogrifier + overwrite: true + contents: + source: https://mytools.example.com/path/to/archive.gz + compression: gzip + verification: + hash: sha512-00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000 + mode: 0555 + links: + - path: /usr/local/bin/transmogrifier + overwrite: true + target: /opt/tools/transmogrifier + hard: false +``` + +#### 7.4.4 编写systemd服务——以启停容器为例 + +``` +variant: nestos +version: 1.0.0 +systemd: + units: + - name: hello.service + enabled: true + contents: | + [Unit] + Description=MyApp + After=network-online.target + Wants=network-online.target + + [Service] + TimeoutStartSec=0 + ExecStartPre=-/bin/podman kill busybox1 + ExecStartPre=-/bin/podman rm busybox1 + ExecStartPre=/bin/podman pull busybox + ExecStart=/bin/podman run --name busybox1 busybox /bin/sh -c ""trap 'exit 0' INT TERM; while true; do echo Hello World; sleep 1; done"" + + [Install] + WantedBy=multi-user.target +``` + +### 7.5 点火文件预集成 + +NestOS构建工具链支持用户根据实际使用场景和需求定制镜像。在镜像制作完成后，nestos-installer还提供了针对镜像部署与应用等方面进行自定义的一系列功能，如嵌入点火文件、预分配安装位置、增删内核参数等功能，以下将针对主要功能进行介绍。 + +#### 7.5.1 点火文件预集成至ISO镜像 + +准备好NestOS的ISO镜像至本地；安装nestos-installer软件包；编辑example.yaml，并使用butane工具将其转换为ign文件，在这里，我们仅配置简单的用户名和密码（密码要求加密，示例中为qwer1234），内容如下： + +``` +variant: nestos +version: 1.0.0 +passwd: + users: + - name: root + password_hash: "$1$root$CPjzNGH.NqmQ7rh26EeXv1" +``` + +将上述yaml转换为ign文件后，执行如下指令嵌入点火文件并指定目标磁盘位置，其中xxx.iso为准备至本地的NestOS ISO镜像： + +``` +nestos-installer iso customize --dest-device /dev/sda --dest-ignition example.ign xxx.iso +``` + +使用该集成点火文件的ISO镜像进行安装时，NestOS会自动读取点火文件并安装至目标磁盘，待进度条完成度为100%后，自动进入安装好的NestOS环境，用户可根据ign文件配置的用户名和密码进入系统。 + +#### 7.5.2 点火文件预集成至PXE镜像 + +准备好NestOS的PXE镜像至本地，组件获取方式参考6.5【获取发布件】章节，其他步骤同上。 + +为了方便用户使用，nestos-installer也支持从ISO镜像中提取PXE组件的功能，执行如下指令，其中xxx.iso为保存至本地的NestOS ISO镜像： + +``` +nestos-installer iso extract pxe xxx.iso +``` + +得到如下输出件： + +``` +xxx-initrd.img +xxx-rootfs.img +xxx-vmlinuz +``` + +执行如下指令嵌入点火文件并指定目标磁盘位置： + +``` +nestos-installer pxe customize --dest-device /dev/sda --dest-ignition example.ign xxx-initrd.img --output custom-initrd.img +``` + +根据使用PXE安装NestOS的方式，替换相应的xxx-initrd.img为custom-initrd.img。启动后NestOS会自动读取点火文件并安装至目标磁盘，待进度条完成度为100%后，自动进入安装好的NestOS环境，用户可根据ign文件配置的用户名和密码进入系统。 + +## 8. 部署流程 + +### 8.1 简介 + +NestOS支持多种部署平台及常见部署方式，当前主要支持qcow2、ISO与PXE三种部署方式。与常见通用OS部署相比，主要区别在于如何传入以ign文件为特征的自定义部署配置，以下各部分将会分别介绍。 + +### 8.2 使用qcow2镜像安装 + +#### 8.2.1 使用qemu创建qcow2实例 + +准备NestOS的qcow2镜像及相应点火文件（详见第7章），终端执行如下步骤： + +``` +IGNITION_CONFIG="/path/to/example.ign" +IMAGE="/path/to/image.qcow2" +IGNITION_DEVICE_ARG="-fw_cfg name=opt/com.coreos/config,file=${IGNITION_CONFIG}" + +qemu-img create -f qcow2 -F qcow2 -b ${IMAGE} my-nestos-vm.qcow2 +``` + +aarch64环境执行如下命令： + +``` +qemu-kvm -m 2048 -M virt -cpu host -nographic -drive if=virtio,file=my-nestos-vm.qcow2 ${IGNITION_DEVICE_ARG} -nic user,model=virtio,hostfwd=tcp::2222-:22 -bios /usr/share/edk2/aarch64/QEMU_EFI-pflash.raw +``` + +x86_64环境执行如下命令： + +``` +qemu-kvm -m 2048 -M pc -cpu host -nographic -drive if=virtio,file=my-nestos-vm.qcow2 ${IGNITION_DEVICE_ARG} -nic user,model=virtio,hostfwd=tcp::2222-:22 +``` + +#### 8.2.2 使用virt-install创建qcow2实例 + +假设libvirt服务正常，网络默认采用default子网，绑定virbr0网桥，您可参考以下步骤创建NestOS实例。 + +准备NestOS的qcow2镜像及相应点火文件（详见第7章），终端执行如下步骤： + +``` +IGNITION_CONFIG="/path/to/example.ign" +IMAGE="/path/to/image.qcow2" +VM_NAME="nestos" +VCPUS="4" +RAM_MB="4096" +DISK_GB="10" +IGNITION_DEVICE_ARG=(--qemu-commandline="-fw_cfg name=opt/com.coreos/config,file=${IGNITION_CONFIG}") +``` + +**注意：使用virt-install安装，qcow2镜像及ign文件需指定绝对路径。** + +执行如下命令创建实例： + +``` +virt-install --connect="qemu:///system" --name="${VM_NAME}" --vcpus="${VCPUS}" --memory="${RAM_MB}" --os-variant="kylin-hostos10.0" --import --graphics=none --disk="size=${DISK_GB},backing_store=${IMAGE}" --network bridge=virbr0 "${IGNITION_DEVICE_ARG[@]} +``` + +### 8.3 使用ISO镜像安装 + +准备NestOS的ISO镜像并启动。首次启动的NestOS ISO镜像会默认进入Live环境，该环境为易失的内存环境。 + +#### 8.3.1 通过nestos-installer安装向导脚本安装OS至目标磁盘 + +1）在NestOS的Live环境中，根据首次进入的打印提示，可输入以下指令，即可自动生成一份简易的点火文件并自动安装重启 + +``` +sudo installnestos +``` + +2）根据终端提示信息依次输入用户名和密码； + +3）选择目标磁盘安装位置，可直接选择回车设置为默认项/dev/sda； + +4）执行完以上步骤后，nestos-installer开始根据我们提供的配置将NestOS安装至目标磁盘，待进度条100%后，自动重启； + +5）重启后自动进入NestOS，在grub菜单直接回车或者等待5s后启动系统，随后根据此前配置的用户名和密码进入系统。至此，安装完成。 + +#### 8.3.2 通过nestos-installer命令手动安装OS至目标磁盘 + +1）准备好点火文件example.ign（详见第7章）； + +2）根据首次进入NestOS的Live环境打印的提示，输入以下指令开始安装： + +``` +sudo nestos-installer install /dev/sda --ignition-file example.ign +``` + +如具备网络条件，点火文件也可通过网络获取，如： + +``` +sudo nestos-installer install /dev/sda --ignition-file http://www.example.com/example.ign +``` + +3）执行完上述指令后，nestos-installer开始根据我们提供的配置将NestOS安装至目标磁盘，待进度条100%后，自动重启； + +4）重启后自动进入NestOS，在gurb菜单直接回车或者等待5s后启动系统，随后根据此前配置的用户名和密码进入系统。至此，安装完成 + +### 8.4 PXE部署 + +NestOS的PXE安装组件包括kernel、initramfs.img和rootfs.img。这些组件以nosa buildextend-live命令生成（详见第6章）。 + +1）使用PXELINUX 的kernel命令行指定内核，简单示例如下： + +``` +KERNEL nestos-live-kernel-x86_64 +``` + +2）使用PXELINUX 的append命令行指定initrd和rootfs，简单示例如下： + +``` +APPEND initrd=nestos-live-initramfs.x86_64.img,nestos-live-rootfs.x86_64.img +``` + +**注意：如您采用7.5章节所述，已将点火文件预集成至PXE组件，则仅需在此进行替换，无需执行后续步骤。** + +3）指定安装位置，以/dev/sda为例，在APPEND后追加，示例如下： + +``` +nestosos.inst.install_dev=/dev/sda +``` + +4）指定点火文件，需通过网络获取，在APPEND后追加相应地址，示例如下： + +``` +nestos.inst.ignition_url=http://www.example.com/example.ign +``` + +5）启动后NestOS会自动读取点火文件并安装至目标磁盘，待进度条完成度为100%后，自动进入安装好的NestOS环境，用户可根据ign文件配置的用户名和密码进入系统。 + +## 9. 基本使用 + +### 9.1 简介 + +NestOS采用基于ostree和rpm-ostree技术的操作系统封装方案，将关键目录设置为只读状态，核心系统文件和配置不会被意外修改；采用overlay分层思想，允许用户在基础ostree文件系统之上分层管理RPM包，不会破坏初始系统体系结构；同时支持构建OCI格式镜像，实现以镜像为最小粒度进行操作系统版本的切换。 + +### 9.2 SSH连接 + +出于安全考虑，NestOS 默认不支持用户使用密码进行SSH登录，而只能使用密钥认证方式。这一设计旨在增强系统的安全性，防止因密码泄露或弱密码攻击导致的潜在安全风险。 + +NestOS通过密钥进行SSH连接的方法与openEuler一致，如果用户需要临时开启密码登录，可按照以下步骤执行： + +1）编辑ssh服务附加配置文件 + +``` +vi /etc/ssh/sshd_config.d/40-disable-passwords.conf +``` + +2）修改默认配置PasswordAuthentication为如下内容： + +``` +PasswordAuthentication yes +``` + +3）重启sshd服务，便可实现临时使用密码进行SSH登录。 + +### 9.3 RPM包安装 + +**注意：不可变操作系统不提倡在运行环境中安装软件包，提供此方法仅供临时调试等场景使用，因业务需求需要变更集成软件包列表请通过更新构建配置重新构建实现。** + +NestOS不支持常规的包管理器dnf/yum，而是通过rpm-ostree来管理系统更新和软件包安装。rpm-ostree结合了镜像和包管理的优势，允许用户在基础系统之上分层安装和管理rpm包，并且不会破环初始系统的结构。使用以下命令安装rpm包： + +``` +rpm-ostree install
规格：
ARM：最大值：512；最小值：1；缺省值：8（配置为0时）
SGX：最大值：4294967295；最小值：1 | - | num_tworkers | 安全侧代理工作线程数，用于执行switchless ECALL。
规格：
ARM：最大值：512；最小值：1；缺省值：8（配置为0时）
SGX：最大值：4294967295；最小值：1 | - | switchless_calls_pool_size | switchless调用任务池的大小，实际可容纳switchless_calls_pool_size * 64个switchless调用任务（例：switchless_calls_pool_size=1，可容纳64个switchless调用任务）。
规格：
ARM：最大值：8；最小值：1；缺省值：1（配置为0时）
SGX：最大值：8；最小值：1；缺省值：1（配置为0时） | - | retries_before_fallback | 执行retries_before_fallback次汇编pause指令后，若switchless调用仍没有被另一侧的代理工作线程执行，就回退到switch调用模式，该字段仅在SGX平台生效。
规格：SGX：最大值：4294967295；最小值：1；缺省值：20000（配置为0时） | - | retries_before_sleep | 执行retries_before_sleep次汇编pause指令后，若代理工作线程一直没有等到有任务来，则进入休眠状态，该字段仅在SGX平台生效。
规格： SGX：最大值：4294967295；最小值：1；缺省值：20000（配置为0时） | - | parameter_num | switchless函数支持的最大参数个数，该字段仅在ARM平台生效。
规格： ARM：最大值：16；最小值：0 | - | workers_policy | switchless代理线程运行模式，该字段仅在ARM平台生效。
规格： ARM： WORKERS_POLICY_BUSY：代理线程一直占用CPU资源，无论是否有任务需要处理，适用于对性能要求极高且系统软硬件资源丰富的场景； WORKERS_POLICY_WAKEUP：代理线程仅在有任务时被唤醒，处理完任务后进入休眠，等待再次被新任务唤醒 | - | rollback_to_common | 异步switchless调用失败时是否回退到普通调用，该字段仅在ARM平台生效。
规格： ARM：0：否，失败时仅返回相应错误码；其他：是，失败时回退到普通调用，此时返回普通调用的返回值 | +| 配置项 | 说明 | +| -------------------------- | ------------------------------------------------------------ | +| num_uworkers | 非安全侧代理工作线程数，用于执行switchless OCALL，当前该字段仅在SGX平台生效，ARM平台可以配置，但是因ARM平台暂不支持OCALL，所以配置后不会生效。
规格：
ARM：最大值：512；最小值：1；缺省值：8（配置为0时）
SGX：最大值：4294967295；最小值：1 | +| num_tworkers | 安全侧代理工作线程数，用于执行switchless ECALL。
规格：
ARM：最大值：512；最小值：1；缺省值：8（配置为0时）
SGX：最大值：4294967295；最小值：1 | +| switchless_calls_pool_size | switchless调用任务池的大小，实际可容纳switchless_calls_pool_size * 64个switchless调用任务（例：switchless_calls_pool_size=1，可容纳64个switchless调用任务）。
规格：
ARM：最大值：8；最小值：1；缺省值：1（配置为0时）
SGX：最大值：8；最小值：1；缺省值：1（配置为0时） | +| retries_before_fallback | 执行retries_before_fallback次汇编pause指令后，若switchless调用仍没有被另一侧的代理工作线程执行，就回退到switch调用模式，该字段仅在SGX平台生效。
规格：SGX：最大值：4294967295；最小值：1；缺省值：20000（配置为0时） | +| retries_before_sleep | 执行retries_before_sleep次汇编pause指令后，若代理工作线程一直没有等到有任务来，则进入休眠状态，该字段仅在SGX平台生效。
规格： SGX：最大值：4294967295；最小值：1；缺省值：20000（配置为0时） | +| parameter_num | switchless函数支持的最大参数个数，该字段仅在ARM平台生效。
规格： ARM：最大值：16；最小值：0 | +| workers_policy | switchless代理线程运行模式，该字段仅在ARM平台生效。
规格： ARM： WORKERS_POLICY_BUSY：代理线程一直占用CPU资源，无论是否有任务需要处理，适用于对性能要求极高且系统软硬件资源丰富的场景； WORKERS_POLICY_WAKEUP：代理线程仅在有任务时被唤醒，处理完任务后进入休眠，等待再次被新任务唤醒 | +| rollback_to_common | 异步switchless调用失败时是否回退到普通调用，该字段仅在ARM平台生效。
规格： ARM：0：否，失败时仅返回相应错误码；其他：是，失败时回退到普通调用，此时返回普通调用的返回值 | +| num_cores | 用于设置安全侧线程绑核
规格： 最大值为当前环境CPU核数 | -2. 定义EDL文件中接口时添加零切换标识transition_using_threads +2.定义EDL文件中接口时添加零切换标识transition_using_threads ```ocaml enclave { @@ -70,17 +72,20 @@ secGear机密计算统一开发框架技术架构如图所示，主要包括三 }; ``` +### 安全传输 +#### 用户痛点 -### 安全通道 -#### 客户痛点 -数据拥有者在请求云上机密计算服务时，需要把待处理数据上传到云上TEE环境中处理，由于TEE没有网络，用户数据需要经过网络先传输到REE，REE接收到数据的明文后，再传入TEE中。用户数据的明文暴露在REE内存中，存在安全风险。 +数据拥有者在请求云上机密计算服务时，需要把待处理数据上传到云上TEE环境中处理，在传输过程中存在数据泄露风险。针对不同网络访问能力的TEE环境，可采用如下解决方案。 -#### 解决方案 -安全通道是一种结合机密计算远程证明，实现数据拥有者与云上TEE之间安全的密钥协商技术，协商出仅数据拥有者与云上TEE拥有的sessionkey，再通过sessionkey加密用户数据，网络传输的是sessionkey加密后的数据，REE接收到密文数据，再传入TEE中解密，处理。 +#### 解决方案1：安全通道 + +该方案针对TEE没有网络的场景，用户数据需要经过网络先传输到REE，由REE再传入TEE中。该方案结合机密计算远程证明，实现数据拥有者与云上TEE之间安全的密钥协商技术，协商出仅数据拥有者与云上TEE拥有的sessionkey，再通过sessionkey加密用户数据，网络传输的是sessionkey加密后的数据，REE接收到密文数据，再传入TEE中解密、处理，该方案称为安全通道。 #### 使用方法 + 安全通道以lib库方式提供，分为客户端、服务端host、服务端enclave三部分，分别由业务程序的客户端、服务端CA、服务端TA调用。 + | 模块 | 头文件 | 库文件 | 依赖 | |------------|--------------------------|-----------------------|---------| | 客户端 | secure_channel_client.h | libcsecure_channel.so | openssl | @@ -88,6 +93,7 @@ secGear机密计算统一开发框架技术架构如图所示，主要包括三 | 服务端enclave | secure_channel_enclave.h | libtsecure_channel.so | TEE及TEE软件栈 | ##### 接口列表 + | 接口名 | 所属头文件、库 | 功能 | 备注 | |----------------------------------------------------------------------------------------------------------------------------------------------|-----------------------|--------------|----| | cc_sec_chl_client_init | secure_channel_client.h libcsecure_channel.so | 安全通道客户端初始化 | 调用前需初始化参数ctx中网络连接和消息发送钩子函数 | @@ -95,15 +101,111 @@ secGear机密计算统一开发框架技术架构如图所示，主要包括三 | cc_sec_chl_client_callback | secure_channel_client.h libcsecure_channel.so | 安全通道协商消息处理函数 | 处理安全通道协商过程中，服务端发送给客户端的消息。在客户端消息接收处调用 | | cc_sec_chl_client_encrypt | secure_channel_client.h libcsecure_channel.so | 安全通道客户端的加密接口 | 无 | | cc_sec_chl_client_decrypt | secure_channel_client.h libcsecure_channel.so | 安全通道客户端的解密接口 | 无 | -| int (*cc_conn_opt_funcptr_t)(void *conn, void *buf, size_t count); | secure_channel.h | 消息发送钩子函数原型 | 由用户客户端和服务端实现，实现中指定安全通道协商消息类型，负责发送安全通道协商消息到对端 | +| int (*cc_conn_opt_funcptr_t)(void*conn, void *buf, size_t count); | secure_channel.h | 消息发送钩子函数原型 | 由用户客户端和服务端实现，实现中指定安全通道协商消息类型，负责发送安全通道协商消息到对端 | | cc_sec_chl_svr_init | secure_channel_host.h libusecure_channel.so | 安全通道服务端初始化 | 调用前需初始化ctx中enclave_ctx | | cc_sec_chl_svr_fini | secure_channel_host.h libusecure_channel.so | 安全通道服务端销毁 | 销毁安全通道服务端以及所有客户端信息 | | cc_sec_chl_svr_callback | secure_channel_host.h libusecure_channel.so | 安全通道协商消息处理函数 | 处理安全通道协商过程中，客户端发送给服务端的消息。在服务端消息接收处调用，调用前需初始化与客户端的网络连接和发送消息函数，详见[样例](https://gitee.com/openeuler/secGear/blob/master/examples/secure_channel/host/server.c#:~:text=conn_ctx.conn_kit.send)。 | | cc_sec_chl_enclave_encrypt | secure_channel_enclave.h libtsecure_channel.so | 安全通道enclave中的加密接口 | 无 | | cc_sec_chl_enclave_decrypt | secure_channel_enclave.h libtsecure_channel.so | 安全通道enclave中的解密接口 | 无 | + ##### 注意事项 + 安全通道仅封装密钥协商过程、加解密接口，不建立网络连接，协商过程复用业务的网络连接。其中客户端和服务端的网络连接由业务建立和维护，在安全通道客户端和服务端初始化时传入消息发送钩子函数和网络连接指针。 详见[安全通道样例](https://gitee.com/openeuler/secGear/tree/master/examples/secure_channel)。 + +#### 解决方案2：RA_TLS + +该方案针对TEE具备网络通信能力的场景，例如：机密虚机/机密容器，具体过程：TA使用自签发证书，证书中包含远程证明材料，在TLS握手过程中使用远程证明服务，对证书中包含的证明材料校验，验证失败则结束握手，否则正常执行握手动作，该方案称为RA_TLS。 +该方案较方案1取消中间数据接收者，同时增加远程证明过程，既实现对TEE环境的校验，又能实现数据加密传输到TA。 + +#### 使用方法 + +RA_TLS以lib库形式提供，使用样例参考[RA_TLS样例](https://gitee.com/openeuler/secGear/tree/master/examples/ra_tls) + +| 头文件 | 库文件 | 依赖 | +|-----------|--------------|---------------------| +| ra_tls.h | libra_tls.so | cjson，curl，TLS库(例如openssl) | + +##### 接口列表 + +| 接口名 | 所属头文件 | 功能 | 备注 | +|-----------------------------|-----------------------|------------------------|---- | +|ra_tls_generate_certificate |ra_tls.h |TA生成自签名证书 |- | +|ra_tls_set_addr |ra_tls.h |设置远程证明Agent地址 |- | +|ra_tls_cert_extension_expired|ra_tls.h |护照模式下检查证书是否过期|仅用于护照模式| +|ra_tls_verify_callback |ra_tls.h |用于握手过程中回调校验证书|- | + +### 远程证明 + +#### 用户痛点 + +随着机密计算技术的发展，逐渐形成几大主流技术（如Arm Trustzone/CCA、Intel SGX/TDX、擎天Enclave、海光CSV等），产品解决方案中可能存在多种机密计算硬件，甚至不同TEE之间的协同，其中远程证明是任何一种机密计算技术信任链的重要一环，每种技术的远程证明报告格式及验证流程各有差异，用户对接不同的TEE，需要集成不同TEE证明报告的验证流程，增加了用户的集成负担，并且不利于扩展新的TEE类型。 + +#### 解决方案 + +secGear远程证明统一框架是机密计算远程证明相关的关键组件，屏蔽不同TEE远程证明差异，提供Attestation Agent和Attestation Service两个组件，Agent供用户集成获取证明报告，对接证明服务；Service可独立部署，支持iTrustee、virtCCA远程证明报告的验证。 + +#### 功能描述 + +远程证明统一框架聚焦机密计算相关功能，部署服务时需要的服务运维等相关能力由服务部署第三方提供。远程证明统一框架的关键技术如下： + +- 报告校验插件框架：支持运行时兼容iTrustee、vritCCA、CCA等不同TEE平台证明报告检验，支持扩展新的TEE报告检验插件。 +- 证书基线管理：支持对不同TEE类型的TCB/TA基线值管理及公钥证书管理，集中部署到服务端，对用户透明。 +- 策略管理：提供默认策略（易用）、用户定制策略（灵活）。 +- 身份令牌：支持对不同TEE签发身份令牌，由第三方信任背书，实现不同TEE类型相互认证。 +- 证明代理：支持对接证明服务/点对点互证，兼容TEE报告获取，身份令牌验证等，易集成，使用户聚焦业务。 + +根据使用场景，支持点对点验证和证明服务验证两种模式。 + +证明服务验证流程如下： + +1.用户（普通节点或TEE）对TEE平台发起挑战。 + +2.TEE平台通过证明代理获取TEE证明报告，并返回给用户。 + +3.用户端证明代理将报告转发到远程证明服务。 + +4.远程证明服务完成报告校验，返回由第三方信任背书的统一格式身份令牌。 + +5.证明代理验证身份令牌，并解析得到证明报告校验结果。 + +6.得到通过的校验结果后，建立安全连接。 + +点对点验证流程(无证明服务)如下： + +1.用户向TEE平台发起挑战，TEE平台返回证明报告给用户。 + +2.用户使用本地点对点TEE校验插件完成报告验证。 + +>  **说明：** +> +> 点对点验证和远程证明服务验证时的证明代理不同，在编译时可通过编译选项，决定编译有证明服务和点对点模式的证明代理。 +> +#### 应用场景 + +在金融、AI等场景下，基于机密计算保护运行中的隐私数据安全时，远程证明是校验机密计算环境及应用合法性的技术手段，远程证明统一框架提供了易集成、易部署的组件，帮助用户快速使能机密计算远程证明能力。 + +### 密钥托管 + +#### 用户痛点 + +机密容器作为云原生与机密计算技术融合的创新型安全方案，通过加密镜像全生命周期防护，有效应对合规性审查、供应链攻击防御及知识产权防泄漏等核心安全诉求。该方案依赖密钥托管为基础，重点构建覆盖密钥安全存储、动态细粒度授权、跨环境协同分发的管理体系，并借助零信任策略与自动化审计能力，在确保数据机密性与操作可追溯性的同时，实现密钥治理复杂度与运维成本的最优平衡，为云原生环境提供“默认加密、按需解密”的一体化防护能力。 + +#### 解决方案 + +secGear的密钥托管方案通过可信硬件认证与动态策略控制构建多层防御体系，并基于远程证明框架实现密钥全生命周期保护。该方案通过远程证明协议验证TEE环境完整性，结合自签名公私钥证书算法，在确保密钥存储安全、传输抗截获、使用可追溯的同时，支持跨云协同与边缘安全场景，实现每秒万级密钥分发的业务吞吐。 + +#### 功能描述 + +针对密钥管理领域的安全性与可信验证需求，secGear框架整合远程证明技术构建分层密钥托管体系： + +1. **证明服务**：通过构建集中式密钥托管服务，基于机密执行环境（TEE）远程证明机制实现对加密镜像密钥的安全存储与生命周期管理，并面向授权用户提供精细化策略配置接口； +2. **证明代理**：在机密计算节点内部署轻量级证明代理组件，提供本地restAPI接口。机密容器运行时通过调用证明代理接口完成机密执行环境的完整性验证，并与服务端建立动态会话实现密钥的安全传输。 + +#### 应用场景 + +secGear的密钥托管功能与Kuasar容器运行时形成完整的机密容器解决方案，适用于任何需要高度数据安全和隐私保护的场景，尤其是在金融、医疗、政府、云计算、物联网等领域。通过容器镜像加密和密钥托管功能，可以有效保护容器镜像的完整性，减少容器数据泄露风险，防止供应链攻击，提升用户对云原生厂商的信任程度。 + ## 缩略语 | 缩略语 | 英文全名 | 中文解释 | @@ -111,3 +213,6 @@ secGear机密计算统一开发框架技术架构如图所示，主要包括三 | REE | Rich Execution Environment | 富执行环境 | | TEE | Trusted Execution Environment | 可信执行环境 | | EDL | Enclave Description Language | 安全应用描述语言 | +| TA | Trusted Application | 可信应用 | +| RA | Remote Attestation | 远程证明 | +| TLS | Transport Layer Security | 传输层安全 | diff --git "a/docs/zh/docs/sysMaster/sysmaster\344\275\277\347\224\250\350\257\264\346\230\216.md" "b/docs/zh/docs/sysMaster/sysmaster\344\275\277\347\224\250\350\257\264\346\230\216.md" index e49a236af6b7b9e91dda7dd9741962edaa8c4a9b..b39bef3db4da92c84ccb577a41a7130aac0a138b 100644 --- "a/docs/zh/docs/sysMaster/sysmaster\344\275\277\347\224\250\350\257\264\346\230\216.md" +++ "b/docs/zh/docs/sysMaster/sysmaster\344\275\277\347\224\250\350\257\264\346\230\216.md" @@ -5,8 +5,6 @@ * 如何创建 `service`服务单元配置文件。 * 如何管理单元服务，例如启动、停止、查看服务。 -更多可以查阅[官方手册](http://sysmaster.online/man/all/)。 - ## 创建单元配置文件 用户可以在 `/usr/lib/sysmaster/system/`目录下创建单元配置文件。 @@ -76,7 +74,7 @@ WantedBy="multi-user.target" 使用以下命令可以启动 `sshd`服务和运行 `ExecStart`所配置的命令。 ```bash -# sctl start sshd.service +sctl start sshd.service ``` ### 停止服务 @@ -84,7 +82,7 @@ WantedBy="multi-user.target" 使用以下命令可以停止 `sshd`服务，杀死 `ExecStart`所运行的进程。 ```bash -# sctl stop sshd.service +sctl stop sshd.service ``` ### 重启服务 @@ -92,7 +90,7 @@ WantedBy="multi-user.target" 使用以下命令可以重启 `sshd`服务，该命令会先停止后启动服务。 ```bash -# sctl restart sshd.service +sctl restart sshd.service ``` ### 查看服务状态 @@ -100,5 +98,5 @@ WantedBy="multi-user.target" 使用以下命令可以查看服务 `sshd`运行状态，用户可以查看服务的状态来获取服务是否正常运行。 ```bash -# sctl status sshd.service +sctl status sshd.service ``` diff --git "a/docs/zh/docs/sysmonitor/figures/sysmonitor\345\212\237\350\203\275\345\210\227\350\241\250.png" "b/docs/zh/docs/sysmonitor/figures/sysmonitor\345\212\237\350\203\275\345\210\227\350\241\250.png" new file mode 100644 index 0000000000000000000000000000000000000000..701e925d66a8771774e1bb38fdf70edd982913bf Binary files /dev/null and "b/docs/zh/docs/sysmonitor/figures/sysmonitor\345\212\237\350\203\275\345\210\227\350\241\250.png" differ diff --git "a/docs/zh/docs/sysmonitor/sysmonitor-\344\275\277\347\224\250\346\211\213\345\206\214.md" "b/docs/zh/docs/sysmonitor/sysmonitor-\344\275\277\347\224\250\346\211\213\345\206\214.md" new file mode 100644 index 0000000000000000000000000000000000000000..a5759d7c6dc5ddb357c553c88386e2287240a8e9 --- /dev/null +++ "b/docs/zh/docs/sysmonitor/sysmonitor-\344\275\277\347\224\250\346\211\213\345\206\214.md" @@ -0,0 +1,799 @@ +# sysmonitor + +## 介绍 + +System Monitor Daemon + +sysmonitor 负责监控 OS 系统运行过程中的异常，将监控到的异常记录到系统日志（`/var/log/sysmonitor.log`）中。sysmonitor 以服务的形式提供，可以通过 `systemctl start|stop|restart|reload sysmonitor` 启动、关闭、重启、重载服务。建议产品部署 sysmonitor 调测软件，便于定位系统异常问题。 + + + +### 注意事项 + +- sysmonitor 不支持并发执行。 +- 各配置文件须合法配置，否则可能造成监控框架异常。 +- sysmonitor 服务操作和配置文件修改，日志查询需要 root 权限。root 用户具有系统最高权限，在使用 root 用户进行操作时，请严格按照操作指导进行操作，避免不规范操作造成系统管理及安全风险。 + +### 配置总览 + +sysmonitor 有一个主配置文件(`/etc/sysconfig/sysmonitor`)，用于配置各监控项的监控周期、是否需要监控。配置项的=和"之间不能有空格,如`PROCESS_MONITOR="on"`。 + +配置说明 + +| 配置项 | 配置项说明 | 是否必配 | 默认值 | +| ------------------------- | ------------------------------------------------------------ | -------- | -------------------------------------- | +| PROCESS_MONITOR | 设定是否开启关键进程监控，on为开启，off为关闭 | 否 | on | +| PROCESS_MONITOR_PERIOD | 设置关键进程监控的周期，单位秒 | 否 | 3s | +| PROCESS_RECALL_PERIOD | 关键进程恢复失败后再次尝试拉起周期，单位分，取值范围为1到1440之间的整数 | 否 | 1min | +| PROCESS_RESTART_TIMEOUT | 关键进程服务异常恢复过程中超时时间，单位秒，取值范围为30至300之间的整数 | 否 | 90s | +| PROCESS_ALARM_SUPRESS_NUM | 设置关键进程监控配置使用告警命令上报告警时的告警抑制次数，取值范围为正整数 | 否 | 5 | +| FILESYSTEM_MONITOR | 设定是否开启 ext3/ext4 文件系统监控，on 为开启，off 为关闭 | 否 | on | +| DISK_MONITOR | 设定是否开启磁盘分区监控，on为开启，off 为关闭 | 否 | on | +| DISK_MONITOR_PERIOD | 设定磁盘监控周期，单位秒 | 否 | 60s | +| INODE_MONITOR | 设定是否开启磁盘 inode 监控，on 为开启， off 为关闭 | 否 | on | +| INODE_MONITOR_PERIOD | 设定磁盘 inode 监控周期，单位秒 | 否 | 开启 | +| NETCARD_MONITOR | 设定是否开启网卡监控，on 为开启， off 为关闭 | 否 | on | +| FILE_MONITOR | 设定是否开启文件监控，on为开启， off 为关闭 | 否 | on | +| CPU_MONITOR | 设定是否开启 cpu 监控，on 为开启， off 为关闭 | 否 | on | +| MEM_MONITOR | 设定是否开启内存监控，on 为开启， off 为关闭 | 否 | on | +| PSCNT_MONITOR | 设定是否开启进程数监控，on为开启，off 为关闭 | 否 | on | +| FDCNT_MONITOR | 设定是否开启 fd 总数监控，on 为开启，off 为关闭 | 否 | on | +| CUSTOM_DAEMON_MONITOR | 用户自定义的 daemon类型的监控项，on为开启，off为关闭 | 否 | on | +| CUSTOM_PERIODIC_MONITOR | 用户自定义的 periodic 类型的监控项，on为开启， off 为关闭 | 否 | on | +| IO_DELAY_MONITOR | 本地磁盘 IO 延时监控开关，on 为开启，off 为关闭 | 否 | off | +| PROCESS_FD_NUM_MONITOR | 设定是否开启单个进程句柄数监控，on为开启，off 为关闭 | 否 | on | +| PROCESS_MONITOR_DELAY | sysmonitor 启动时，是否等待所有的监控项都正常，on为等待，off为不等待 | 否 | on | +| NET_RATE_LIMIT_BURST | 网卡监控路由信息打印抑制频率，即一秒内打印多少条日志 | 否 | 5
有效范围是 0-100，默认为5 | +| FD_MONITOR_LOG_PATH | 文件句柄监控日志文件 | 否 | 默认配置路径为 /var/log/sysmonitor.log | +| ZOMBIE_MONITOR | 僵尸进程监控开关 | 否 | off | +| CHECK_THREAD_MONITOR | 内部线程自愈开关，on为开启，off为关闭 | 否 | on
若不配置，默认值为开启 | +| CHECK_THREAD_FAILURE_NUM | 内部线程自愈的周期检查次数 | 否 | 默认值为3，范围为【2,10】 | + +- 修改 `/etc/sysconfig/sysmonitor` 配置文件后，需要重启 sysmonitor 服务生效。 +- 配置文件中，如果某一项没有配置，默认为监控项开启。 +- 内部线程自愈开启后，当监控项子线程卡住，且超过配置的周期检查次数，会重启 sysmonitor 服务，进行恢复，会重新加载配置，对于配置的关键进程监控和自定义监控，会重新拉起执行。如果对于用户使用有影响，可以选择关闭该功能。 + +### 命令参考 + +- 启动监控服务 + +``` shell +systemctl start sysmonitor +``` + +- 关闭监控服务 + +``` shell +systemctl stop sysmonitor +``` + +- 重启监控服务 + +``` shell +systemctl restart sysmonitor +``` + +- 修改监控项的配置文件后，重载监控服务可使修改后的配置动态生效 + +``` shell +systemctl reload sysmonitor +``` + +### 监控日志 + +在默认情况下，为了防止 sysmonitor.log 文件过大，提供了切分转储日志的机制。日志将被转储到磁盘目录下，这样就能够保持一定量的日志。 + +配置文件为`/etc/rsyslog.d/sysmonitor.conf`，因为增加了rsyslog配置文件，第一次安装 sysmonitor 后，需要重启 rsyslog 服务生效 sysmonitor 日志配置。 + +``` shell +$template sysmonitorformat,"%TIMESTAMP:::date-rfc3339%|%syslogseverity-text%|%msg%\n" + +$outchannel sysmonitor, /var/log/sysmonitor.log, 2097152, /usr/libexec/sysmonitor/sysmonitor_log_dump.sh +if ($programname == 'sysmonitor' and $syslogseverity <= 6) then { +:omfile:$sysmonitor;sysmonitorformat +stop +} + +if ($msg contains 'Time has been changed') then { +:omfile:$sysmonitor;sysmonitorformat +stop +} + +if ($programname == 'sysmonitor' and $syslogseverity > 6) then { +/dev/null +stop +} +``` + +## ext3/ext4 文件系统监控 + +### 简介 + +当文件系统出现故障时会导致 IO 操作异常从而引发操作系统一系列问题。通过文件系统故障检测及时发现，以便于系统管理员或用户及时处理故障，修复问题。 + +### 配置文件说明 + +无 + +### 异常日志 + +对于增加了 errors=remount-ro 挂载选项的文件系统，如果监控到 ext3/ext4文件系统故障，sysmonitor.log 中打印异常信息示例如下： + +``` shell +info|sysmonitor[127]: loop0 filesystem error. Remount filesystem read-only. +``` + +其他异常场景下，如果监控到 ext3/ext4 文件系统故障，sysmonitor.log 中打印异常信息示例如下： + +``` shell +info|sysmonitor[127]: fs_monitor_ext3_4: loop0 filesystem error. flag is 1879113728. +``` + +## 关键进程监控 + +### 简介 + +定期监控系统中关键进程，当系统内关键进程异常退出时，自动尝试恢复关键进程。如果恢复失败并需要告警，可上报告警。系统管理员能被及时告知进程异常退出事件，以及进程是否被恢复拉起。问题定位人员能从日志中定位进程异常退出的时间。 + +### 配置文件说明 + +配置目录为`/etc/sysmonitor/process`, 每个进程或模块一个配置文件。 + +``` shell +USER=root +NAME=irqbalance +RECOVER_COMMAND=systemctl restart irqbalance +MONITOR_COMMAND=systemctl status irqbalance +STOP_COMMAND=systemctl stop irqbalance +``` + +各配置项如下： + +| 配置项 | 配置项说明 | 是否必配 | 默认值 | +| ---------------------- | ------------------------------------------------------------ | -------- | --------------------------------------------------- | +| NAME | 进程或模块名 | 是 | 无 | +| RECOVER_COMMAND | 恢复命令 | 否 | 无 | +| MONITOR_COMMAND | 监控命令
命令返回值为0视为进程正常，命令返回大于 0视为进程异常 | 否 | pgrep -f $(which xxx) "xxx"为NAME字段中配置的进程名 | +| STOP_COMMAND | 停止命令 | 否 | 无 | +| USER | 用户名
使用指定的用户执行、监控、恢复、停止命令或脚本 | 否 | 如果配置项为空，则默认使用 root | +| CHECK_AS_PARAM | 参数传递开关
开关设置为 on 时，在执行 RECOVER_COMMAND 命令时，会将 MONITOR_COMMAND 的返回值作为入参，传给 RECOVER_COMMAND 命令或脚本。 开关为 off 或其他时，功能关闭 | 否 | 无 | +| MONITOR_MODE | 监控模式
- 配置为 parallel，并行监控
- 配置为 serial，串行监控 | 否 | serial | +| MONITOR_PERIOD | 监控周期
- 并行监控监控周期
- 监控模块配置为 serial，该配置项不生效 | 否 | 3 | +| USE_CMD_ALARM | 告警模式
配置为 on 或 ON，则使用告警命令上报告警 | 否 | 无 | +| ALARM_COMMAND | 上报告警命令 | 否 | 无 | +| ALARM_RECOVER_COMMAND | 恢复告警命令 | 否 | 否 | + +- 修改关键进程监控的配置文件后，须执行 `systemctl reload sysmonitor`， 新的配置在一个监控周期后生效。 +- 恢复命令和监控命令不阻塞，否则会造成关键进程监控线程异常。 +- 当恢复命令执行超过 90 s时，会调用停止命令终止进程。 +- 当恢复命令配置为空或不配置时，监控命令检查到关键进程异常时，不会尝试进行拉起。 +- 当关键进程异常时，并且尝试拉起三次都不成功，最终会按照全局配置文件中配置的 PROCESS_RECALL_PERIOD 周期进行拉起。 +- 当监控的进程不是 daemon 进程，MONITOR_COMMAND 必配。 +- 若配置的关键服务在当前系统上不存在，则该监控不会生效，日志中会有相应提示；其他配置项，出现致命性错误，将使用默认配置，不报错。 +- 配置文件权限为 600，监控项建议为 systemd 中的 service类型（如 MONITOR_COMMAND=systemctl status irqbalance）, 若监控的为进程，请确保 NAME 字段为绝对路径。 +- sysmonitor 重启（restart）、重载（reload）、退出（stop）都不会影响所监控的进程或服务。 +- 若 USE_CMD_ALARM 的配置为 on，ALARM_COMMAND、ALARM_RECOVER_COMMAND 的配置由用户保障。ALARM_COMMAND、ALARM_RECOVER_COMMAND 为空或没有配置，则不上报告警。 +- 对于用户自行配置的命令，如监控命令，恢复命令，停止命令，上报告警命令，恢复告警命令等，命令的安全性由用户保证。命令由 root 权限执行，建议脚本命令权限设置为仅供 root 使用，避免普通用户提权风险。 +- 配置监控命令的长度不大于200，大于 200，添加进程监控失败。 +- 当恢复命令配置为 systemd 的重启服务命令时（如`RECOVER_COMMAND=systemctl restart irqbalance`），需注意是否与开源 systemd 恢复服务的机制冲突，否则可能会影响关键进程异常后的行为模式。 +- 由 sysmonitor 恢复拉起的进程将和 sysmonitor 服务在同一个 Cgroup 当中，无法单独进行资源限制，因此建议优先使用开源 systemd 机制进行恢复。 + +### 异常日志 + +- 配置 RECOVER_COMMAND + + 如果监控到进程或模块异常，/var/log/sysmonitor.log 中打印异常信息示例如下： + + ``` shell + info|sysmonitor[127]: irqbalance is abnormal, check cmd return 1, use "systemctl restart irqbalance" to recover + ``` + + 如果监控到进程或模块恢复正常，/var/log/sysmonitor.log 中打印日志示例如下： + + ``` shell + info|sysmonitor[127]: irqbalance is recovered + ``` + +- 不配置 RECOVER_COMMAND + + 如果监控到进程或模块异常，/var/log/sysmonitor.log 中打印异常信息示例如下： + + ``` shell + info|sysmonitor[127]: irqbalance is abnormal, check cmd return 1, recover cmd is null, will not recover + ``` + + 如果监控到进程或模块恢复正常，/var/log/sysmonitor.log 中打印日志示例如下： + + ``` shell + info|sysmonitor[127]: irqbalance is recovered + ``` + +## 文件监控 + +### 简介 + +系统关键文件被意外删除后，会导致系统运行异常甚至崩溃。通过文件监控可以及时获知系统中关键文件被删除或者有恶意文件被添加，以便管理员和用户及时获知并处理故障。 + +### 配置文件说明 + +配置文件为 `/etc/sysmonitor/file`。每个监控配置项为一行，监控配置项包含两个内容：监控文件（目录）和监控事件。监控文件（目录）是绝对路径，监控文件（目录）和监控事件中间由一个或多个空格隔开。 + +配置文件支持在`/etc/sysmonitor/file.d` 目录下增加文件监控项配置，配置方法与 `/etc/sysmonitor/file` 相同。 + +- 由于日志长度限制，建议配置的文件和目录绝对路径长度小于 223。如果配置的监控对象绝对路径长度超过223，可能会有日志打印不完整的现象出现。 + +- 请用户自行确保监控文件路径正确，如果配置文件不存在或路径错误则无法监控到该文件。 + +- 由于系统路径长度限制，监控的文件或目录绝对路径长度必须小于 4096。 + +- 支持监控目录和常规文件，/proc 和 /proc/* /dev和/dev/* /sys和/sys/* 管道文件 socket 文件等均不支持监控。 + +- /var/log 和 /var/log/* 均只支持删除事件。 + +- 当配置文件中存在多个相同路径的时候，以第一条合法配置为准，其他相同配置均不生效。在日志文件中可以查看到其他相同配置被忽略的提示。 + +- 不支持对软链接配置监控；当配置硬链接文件的删除事件时，需删除该文件和它的全部硬链接才会打印文件删除事件。 + +- 当文件添加监控成功及监控的事件发生时，监控日志打印的是配置文件中路径的绝对路径。 + +- 目前暂不支持目录递归监控，只能监控配置文件中的目录，子目录不会监控。 + +- 监控文件（目录）采用了位图的方式配置要监控的事件，对文件或目录进行监控的事件位图如下所示： + +``` shell + ------------------------------- + | 11~32 | 10 | 9 | 1~8 | + ------------------------------- +``` + +事件位图每一位代表一个事件，第N位如果置1，则表示监控第n位对应的事件；如果第 n 位置 0，则表示不监控第 n 位对应的事件。监控位图对应的 16 进制数，即是写到配置文件中的监控事件项。 + +| 配置项 | 配置项说明 | 是否必配 | +| ------ | ------------------ | -------- | +| 1~8 | 保留 | 否 | +| 9 | 文件、目录添加事件 | 是 | +| 10 | 文件、目录删除事件 | 是 | +| 11~32 | 保留 | 否 | + +- 修改文件监控的配置文件后，须执行`systemctl reload sysmonitor`，新的配置在最多60秒后生效。 +- 监控事件需要严格遵守上述规则，如果配置有误，则无法监控；如果配置项中监控事件为空，则默认只监控删除事件，即0x200。 +- 文件或目录删除后，只有当所有打开该文件的进程都停止后才会上报删除事件。 +- 监控的文件通过 vi、sed 等操作修改后会在监控日志中打印 File "XXX" may have been changed。 +- 文件监控目前实现了对添加和删除事件的监控，即第9位和第10位有效，其他位为保留位，暂不生效。如果配置了保留位，监控日志会提示监控事件配置错误。 + +**示例** + +配置对 /home 下子目录的增加和删除事件监控，低12 位位图为：001100000000，则可以配置如下： + +``` shell +/home 0x300 +``` + +配置对 /etc/ssh/sshd_config 文件的删除事件监控，低12位位图为：001000000000，则可以配置如下： + +``` shell +/etc/sshd/sshd_config 0x200 +``` + +### 异常日志 + +如果监控文件有配置的事件发生，/var/log/sysmonitor.log 中打印日志示例如下： + +``` shell +info|sysmonitor[127]: 1 events queued +info|sysmonitor[127]: 1th events handled +info|sysmonitor[127]: Subfile "111" under "/home" was added. +``` + +## 磁盘分区监控 + +### 简介 + +定期监控系统中挂载的磁盘分区空间，当磁盘分区使用率大于或等于用户设置的告警阈值时，记录磁盘空间告警。当磁盘分区使用率小于用户设置的告警恢复阈值时，记录磁盘空间恢复告警。 + +### 配置文件说明 + +配置文件为 `/etc/sysmonitor/disk`。 + +``` shell +DISK="/var/log" ALARM="90" RESUME="80" +DISK="/" ALARM="95" RESUME="85" +``` + +| 配置项 | 配置项说明 | 是否必配 | 默认值 | +| ------ | ---------------------- | -------- | ------ | +| DISK | 磁盘挂载目录名 | 是 | 无 | +| ALARM | 整数，磁盘空间告警阈值 | 否 | 90 | +| RESUME | 整数，磁盘空间恢复阈值 | 否 | 80 | + +- 修改磁盘空间监控的配置文件后，须执行 systemctl reload sysmonitor，新的配置在一个监控周期后生效。 +- 重复配置的挂载目录，最后一个配置项生效。 +- ALARM 值应该大于 RESUME 值。 +- 只能针对挂载点或被挂载点的磁盘分区做监控。 +- 在 CPU 和 IO 高压场景下，df 命令执行超时，会导致磁盘利用率获取不到。 +- 当多个挂载点对应同一个磁盘分区时，以挂载点为准来上报告警。 + +### 异常日志 + +如果监控到磁盘空间告警，`/var/log/sysmonitor.log`中打印信息示例如下： + +``` shell +warning|sysmonitor[127]: report disk alarm, /var/log used:90% alarm:90% +info|sysmonitor[127]: report disk recovered, /var/log used:4% resume:10% +``` + +## 网卡状态监控 + +### 简介 + +系统运行过程中可能出现人为原因或异常而导致网卡状态或 IP 发生改变，对网卡状态和 IP 变化进行监控，以便及时感知到异常并方便定位异常原因。 + +### 配置文件说明 + +配置文件为 `/etc/sysmonitor/network`。 + +``` shell +#dev event +eth1 UP +``` + +各配置项说明如下表 +| 配置项 | 配置项说明 | 是否必配 | 默认值 | +| ------ | ------------------------------------------------------------ | -------- | ------------------------------------------------- | +| dev | 网卡名 | 是 | 无 | +| event | 侦听事件，可取 UP, DOWN,NEWADDR, DELADDR.
- UP： 网卡 UP
- DOWN： 网卡 DOWN
- NEWADDR： 增加 ip 地址
- DELADDR： 删除 ip 地址 | 否 | 若侦听事件为空则 UP，DOWN，NEWADDR，DELADDR都监控 | + +- 修改网卡监控的配置文件后，执行 `systemctl reload sysmonitor`，新的配置生效。 +- 不支持虚拟网卡 UP 和 DOWN 状态监控。 +- 请确保网卡监控的配置文件每行少于 4096 个字符，若超过4096个字符会在监控日志中打印配置错误的提示信息。 +- 默认监控所有网卡的所有事件信息，即不配置任何网卡，默认监控所有网卡的 UP，DOWN，NEWADDR，DELADDR 事件。 +- 如果配置网卡，不配置事件，则默认监控改网卡的所有事件。 +- 增加路由信息，默认一秒五条，可通过/etc/sysconfig/sysmonitor 的 NET_RATE_LIMIT_BURST 配置选项配置一秒钟打印路由信息数量。 + +### 异常日志 + +如果监控到配置的网卡事件，`/var/log/sysmonitor.log` 中打印信息示例如下： + +``` shell +info|sysmonitor[127]: lo: ip[::1] prefixlen[128] is added, comm: (ostnamed)[1046], parent comm: syst emd[1] +info|sysmonitor[127]: lo: device is up, comm: (ostnamed)[1046], parent comm: systemd[1] +``` + +如果监控到路由事件, `/var/log/sysmonitor.log` 中打印信息示例如下： + +``` shell +info|sysmonitor[881]: Fib4 replace table=255 192.168.122.255/32, comm: daemon-init[1724], parent com m: systemd[1] +info|sysmonitor[881]: Fib4 replace table=254 192.168.122.0/24, comm: daemon-init[1724], parent comm: systemd[1] +info|sysmonitor[881]: Fib4 replace table=255 192.168.122.0/32, comm: daemon-init[1724], parent comm: systemd[1] +info|sysmonitor[881]: Fib6 replace fe80::5054:ff:fef6:b73e/128, comm: kworker/1:3[209], parent comm: kthreadd[2] +``` + +## cpu 监控 + +### 简介 + +监控系统全局或指定域内 cpu 的占用情况，当 cpu 使用率超出用户设置的告警阈值时，执行用户配置的日志收集命令。 + +### 配置文件说明 + +配置文件为`/etc/sysmonitor/cpu`。 + +当监控系统全局 cpu 时，配置文件示例如下： + +``` shell +# cpu usage alarm percent +ALARM="90" + +# cpu usage alarm resume percent +RESUME="80" + +# monitor period (second) +MONITOR_PERIOD="60" + +# stat period (second) +STAT_PERIOD="300" + +# command executed when cpu usage exceeds alarm percent +REPORT_COMMAND="" +``` + +当监控系统指定域 cpu 时，配置文件示例如下： + +``` shell +# monitor period (second) +MONITOR_PERIOD="60" + +# stat period (second) +STAT_PERIOD="300" + +DOMAIN="0,1" ALARM="90" RESUME="80" +DOMAIN="2,3" ALARM="50" RESUME="40" + +# command executed when cpu usage exceeds alarm percent +REPORT_COMMAND="" +``` + +| 配置项 | 配置项说明 | 是否必配 | 默认值 | +| -------------- | ------------------------------------------------------------ | -------- | ------ | +| ALARM | 大于0，cpu 使用率告警阈值 | 否 | 90 | +| RESUME | 大于等于0，cpu 使用率恢复阈值 | 否 | 80 | +| MONITOR_PERIOD | 监控周期（秒），取值大于0 | 否 | 60 | +| STAT_PERIOD | 统计周期（秒），取值大于0 | 否 | 300 | +| DOMAIN | 域内的 cpu 信号，cpu 号均以十进制数字表示
- 可以通过列举方式指定，cpu 号之间通过逗号分隔，例如：1,2,3。也可以通过范围方式指定，格式 X-Y（X
daemon：后台运行
periodic：周期运行 | 是 | 无 | +| EXECSTART | 执行监控命令 | 是 | 无 | +| ENVIROMENTFILE | 环境变量存放文件 | 否 | 无 | +| PERIOD | 若 type 为 periodic 类型，此为必配项，为自定义监控的周期，取值为大于0的整数 | periodic 类型为必配项 | 无 | + +- 配置文件名称，环境变量文件名称，加上绝对路径总长度不能超过127个字符。环境变量文件必须为绝对路径和实际路径，不能是软链接路径。 +- EXECSTART项的命令总长度不能超过159个字符，关键字段配置不能有空格。 +- 周期性监控的执行命令不能超时，否则对自定义监控框架产生影响。 +- 目前支持配置的环境变量最多为256个。 +- daemon 类型的自定义监控每间隔10s会统一查询是否有 reload 命令下发，或者是否有 daemon 进程异常退出；如果有reload 命令下发，需要等待 10s 后才会重新加载新的配置，如果有 daemon 进程异常退出，需要等待 10s才会重新拉起。 +- ENVIROMENTFLE 对应的文件中的内容发生变化，如新增环境变量，或环境变量的值发生变化，需要重启 sysmonitor 服务，新的环境变量才能生效。 +- `/etc/sysmonitor.d/`目录下的配置文件权限建议为 600， EXECSTART 项中若只配置了执行文件，则执行文件的权限建议为 550。 +- daemon 进程异常退出后，sysmonitor 会重新加载该 daemon进程的配置文件。 + +### 异常日志 + +如果 daemon 类型监控项异常退出，/var/log/sysmonitor.log 中会有如下记录： + +``` shell +info|sysmonitor[127]: custom daemon monitor: child process[11609] name unetwork_alarm exit code[127],[1] times. +``` diff --git a/docs/zh/docs/thirdparty_migration/openstack.md b/docs/zh/docs/thirdparty_migration/openstack.md index 05dd965ac5ea6eaa293805b3ab2ce0478d298e4e..12a6cbce8d096144d41d64509786a741dde07888 100644 --- a/docs/zh/docs/thirdparty_migration/openstack.md +++ b/docs/zh/docs/thirdparty_migration/openstack.md @@ -1,3 +1,3 @@ # openEuler OpenStack -openEuler OpenStack相关文档已迁移至[OpenStack SIG官网文档](https://openeuler.gitee.io/openstack/)。请访问链接获取详细信息。 +openEuler OpenStack相关文档已迁移至[OpenStack SIG官网文档](https://openstack-sig.readthedocs.io/zh/latest/)。请访问链接获取详细信息。 diff --git a/docs/zh/docs/userguide/images/packagemanagement.png b/docs/zh/docs/userguide/images/packagemanagement.png index 6d314e2c6ad6bafd321d9f76cd6aa5f17a8cb394..915001f44cb143c26b10e9e71bcfaaf6ee3aef06 100644 Binary files a/docs/zh/docs/userguide/images/packagemanagement.png and b/docs/zh/docs/userguide/images/packagemanagement.png differ diff --git a/docs/zh/docs/userguide/patch-tracking.md b/docs/zh/docs/userguide/patch-tracking.md index 7bc864e6e1e03f58afc88bd9305cd54ab563b0cc..86a34288196f4287841c24eeaddf07e98f41e301 100644 --- a/docs/zh/docs/userguide/patch-tracking.md +++ b/docs/zh/docs/userguide/patch-tracking.md @@ -288,19 +288,3 @@ rpm 包获取地址：[https://repo.openeuler.org/](https://repo.openeuler.org/) ### 码云查看 issue 及 PR 登录Gitee上进行跟踪的软件项目，在该项目的Issues和Pull Requests页签下，可以查看到名为`[patch tracking] TIME`，例如`[patch tracking] 20200713101548`的条目，该条目即是刚生成的补丁文件的issue和对应PR。 - -## FAQ - -### 访问 api.github.com Connection refused 异常 - -#### 问题描述 - -patch-tracking 运行过程中，可能会出现如下报错： - -``` - 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('