diff --git a/docs/en/docs/A-Ops/figures/icon-note.gif b/docs/en/docs/A-Ops/figures/icon-note.gif new file mode 100644 index 0000000000000000000000000000000000000000..6314297e45c1de184204098efd4814d6dc8b1cda Binary files /dev/null and b/docs/en/docs/A-Ops/figures/icon-note.gif differ diff --git a/docs/en/docs/A-Ops/using-gala-anteater.md b/docs/en/docs/A-Ops/using-gala-anteater.md index 235f7f7e8487f8b2cec9072e75341ddc262ca14e..1eda775528658a509460924454380cb4fd897536 100644 --- a/docs/en/docs/A-Ops/using-gala-anteater.md +++ b/docs/en/docs/A-Ops/using-gala-anteater.md @@ -1,160 +1,220 @@ # Using gala-anteater -gala-anteater is an AI-based operating system exception detection platform. It provides functions such as time series data preprocessing, exception detection, and exception reporting. Based on offline pre-training, online model incremental learning and model update, it can be well adapted to multi-dimensional and multi-modal data fault diagnosis. +gala-anteater is an AI-based OS exception detection platform. It provides functions such as time series data preprocessing, exception detection, and exception reporting. Based on offline pre-training, online model incremental learning and model update, it can be well adapted to multi-dimensional and multi-modal data fault diagnosis. This chapter describes how to deploy and use the gala-anteater service. ## Installation -Mount the repo sources. +Mount the repositories. -```text -[oe-22.03-lts-sp3-everything] # openEuler 22.03-LTS-SP3 official repository -name=oe-2203-lts-sp3-everything -baseurl=http://repo.openeuler.org/openEuler-22.03-LTS-SP3/everything/x86_64/ +```basic +[everything] +name=everything +baseurl=http://121.36.84.172/dailybuild/EBS-openEuler-22.03-LTS-SP4/EBS-openEuler-22.03-LTS-SP4/everything/$basearch/ enabled=1 gpgcheck=0 priority=1 -[oe-22.03-lts-sp3-epol-update] # openEuler 22.03-LTS-SP3 Update official repository -name=oe-22.03-lts-sp3-epol-update -baseurl=http://repo.openeuler.org/openEuler-22.03-LTS-SP3/EPOL/update/main/x86_64/ +[EPOL] +name=EPOL +baseurl=http://repo.openeuler.org/EBS-openEuler-22.03-LTS-SP4/EPOL/main/$basearch/ enabled=1 gpgcheck=0 priority=1 -[oe-22.03-lts-sp3-epol-main] # openEuler 22.03-LTS-SP3 EPOL official repository -name=oe-22.03-lts-sp3-epol-main -baseurl=http://repo.openeuler.org/openEuler-22.03-LTS-SP3/EPOL/main/x86_64/ -enabled=1 -gpgcheck=0 -priority=1 ``` Install gala-anteater. ```bash -# yum install gala-anteater +yum install gala-anteater ``` ## Configuration -> Note: Some gala-anteater parameters can be configured in **/etc/gala-anteater/config/gala-anteater.yaml**. - -### Startup Parameters - -| Parameter| Parameter Full Name| Type| Mandatory (Yes/No)| Default Value| Name| Description| -|---|---|---|---|---|---|---| -| -ks | --kafka_server | string | True | | KAFKA_SERVER | IP address of the Kafka server, for example, **localhost / xxx.xxx.xxx.xxx**.| -| -kp | --kafka_port | string | True | | KAFKA_PORT | Port number of the Kafka server, for example, **9092**.| -| -ps | --prometheus_server | string | True | | PROMETHEUS_SERVER | IP address of the Prometheus server, for example, **localhost / xxx.xxx.xxx.xxx**.| -| -pp | --prometheus_port | string | True | | PROMETHEUS_PORT | Port number of the Prometheus server, for example, **9090**.| -| -m | --model | string | False | vae | MODEL | Exception detection model. Currently, two exception detection models are supported: **random_forest** and **vae**.
**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.| - -## Start - -Start gala-anteater. - -> Note: gala-anteater can be started and run in command line mode, but cannot be started and run in systemd mode. - -- Running in online training mode (recommended) - -```bash -gala-anteater -ks {ip} -kp {port} -ps {ip} -pp {port} -m vae -r True -l 7 -t 0.6 -sli 400 +>![](./figures/icon-note.gif)**Note:** +> +> gala-anteater uses a configuration file to set parameters during startup. The configuration file is located at **/etc/gala-anteater/config/gala-anteater.yaml**. + +### Default Configuration Parameters + +```yaml +Global: + data_source: "prometheus" + +Arangodb: + url: "http://localhost:8529" + db_name: "spider" + +Kafka: + 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 + +Schedule: + duration: 1 + +Suppression: + interval: 10 ``` -- Running in common mode +| Parameter | Description | Default Value | +| ----------- | ------------------------------------------------------------------------------------------- | ---------------------------- | +| Global | Global configuration | Dictionary type | +| data_source | Data source | "prometheus" | +| Arangodb | ArangoDB graph database configuration | Dictionary type | +| url | Graph database IP address | "" | +| db_name | Graph database name | "spider" | +| Kafka | Kafka configuration | Dictionary type | +| server | Kafka server IP address | "192.168.122.100" | +| port | Kafka server port number | "9092" | +| model_topic | Topic for reporting fault detection results | "gala_anteater_hybrid_model" | +| rca_topic | Topic for reporting root cause analysis results | "gala_cause_inference" | +| meta_topic | Topic for gopher-collected metric data | "gala_gopher_metadata" | +| group_id | Kafka group name | "gala_anteater_kafka" | +| Prometheus | Prometheus data source configuration | Dictionary type | +| server | Prometheus server IP address | "localhost" | +| port | Prometheus server port number | "9090" | +| steps | Metric sampling interval | "5" | +| Schedule | Loop scheduling configuration | Dictionary type | +| duration | Execution frequency of the exception detection model in minutes | 1 | +| Suppression | Alarm suppression configuration | Dictionary type | +| interval | Alarm suppression interval filtering the same alarm within _x_ minutes after the last alarm | 10 | + +## Startup + +Run the following command to start gala-anteater: ```bash -gala-anteater -ks {ip} -kp {port} -ps {ip} -pp {port} -m vae -t 0.6 -sli 400 +systemctl start gala-anteater ``` -Query the gala-anteater service status. +>![](./figures/icon-note.gif)**Note:** +> +> gala-anteater supports only one process instance. Starting multiple instances may cause excessive memory usage and log inconsistencies. + +### Execution Status of Slow Node Detection in gala-anteater Service -If the following information is displayed, the service is started successfully. The startup log is saved to the **logs/anteater.log** file in the current running directory. +If the log shows the following content, it means slow node detection is functioning correctly. The startup log is also saved in **/var/log/gala-anteater/gala-anteater.log**. ```log -2022-09-01 17:52:54,435 - root - INFO - Run gala_anteater main function... -2022-09-01 17:52:54,436 - root - INFO - Start to try updating global configurations by querying data from Kafka! -2022-09-01 17:52:54,994 - root - INFO - Loads metric and operators from file: xxx\metrics.csv -2022-09-01 17:52:54,997 - root - INFO - Loads metric and operators from file: xxx\metrics.csv -2022-09-01 17:52:54,998 - root - INFO - Start to re-train the model based on last day metrics dataset! -2022-09-01 17:52:54,998 - root - INFO - Get training data during 2022-08-31 17:52:00+08:00 to 2022-09-01 17:52:00+08:00! -2022-09-01 17:53:06,994 - root - INFO - Spends: 11.995422840118408 seconds to get unique machine_ids! -2022-09-01 17:53:06,995 - root - INFO - The number of unique machine ids is: 1! -2022-09-01 17:53:06,996 - root - INFO - Fetch metric values from machine: xxxx. -2022-09-01 17:53:38,385 - root - INFO - Spends: 31.3896164894104 seconds to get get all metric values! -2022-09-01 17:53:38,392 - root - INFO - The shape of training data: (17281, 136) -2022-09-01 17:53:38,444 - root - INFO - Start to execute vae model training... -2022-09-01 17:53:38,456 - root - INFO - Using cpu device -2022-09-01 17:53:38,658 - root - INFO - Epoch(s): 0 train Loss: 136.68 validate Loss: 117.00 -2022-09-01 17:53:38,852 - root - INFO - Epoch(s): 1 train Loss: 113.73 validate Loss: 110.05 -2022-09-01 17:53:39,044 - root - INFO - Epoch(s): 2 train Loss: 110.60 validate Loss: 108.76 -2022-09-01 17:53:39,235 - root - INFO - Epoch(s): 3 train Loss: 109.39 validate Loss: 106.93 -2022-09-01 17:53:39,419 - root - INFO - Epoch(s): 4 train Loss: 106.48 validate Loss: 103.37 -... -2022-09-01 17:53:57,744 - root - INFO - Epoch(s): 98 train Loss: 97.63 validate Loss: 96.76 -2022-09-01 17:53:57,945 - root - INFO - Epoch(s): 99 train Loss: 97.75 validate Loss: 96.58 -2022-09-01 17:53:57,969 - root - INFO - Schedule recurrent job with time interval 1 minute(s). -2022-09-01 17:53:57,973 - apscheduler.scheduler - INFO - Adding job tentatively -- it will be properly scheduled when the scheduler starts -2022-09-01 17:53:57,974 - apscheduler.scheduler - INFO - Added job "partial" to job store "default" -2022-09-01 17:53:57,974 - apscheduler.scheduler - INFO - Scheduler started -2022-09-01 17:53:57,975 - apscheduler.scheduler - DEBUG - Looking for jobs to run -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) +2024-12-02 16:25:20,727 - INFO - anteater - Groups-0, metric: npu_chip_info_hbm_used_memory, start detection. +2024-12-02 16:25:20,735 - INFO - anteater - Metric-npu_chip_info_hbm_used_memory single group has data 8. ranks: [0, 1, 2, 3, 4, 5, 6, 7] +2024-12-02 16:25:20,739 - INFO - anteater - work on npu_chip_info_hbm_used_memory, slow_node_detection start. +2024-12-02 16:25:21,128 - INFO - anteater - time_node_compare result: []. +2024-12-02 16:25:21,137 - INFO - anteater - dnscan labels: [-1 0 0 0 -1 0 -1 -1] +2024-12-02 16:25:21,139 - INFO - anteater - dnscan labels: [-1 0 0 0 -1 0 -1 -1] +2024-12-02 16:25:21,141 - INFO - anteater - dnscan labels: [-1 0 0 0 -1 0 -1 -1] +2024-12-02 16:25:21,142 - INFO - anteater - space_nodes_compare result: []. +2024-12-02 16:25:21,142 - INFO - anteater - Time and space aggregated result: []. +2024-12-02 16:25:21,144 - INFO - anteater - work on npu_chip_info_hbm_used_memory, slow_node_detection end. + +2024-12-02 16:25:21,144 - INFO - anteater - Groups-0, metric: npu_chip_info_aicore_current_freq, start detection. +2024-12-02 16:25:21,153 - INFO - anteater - Metric-npu_chip_info_aicore_current_freq single group has data 8. ranks: [0, 1, 2, 3, 4, 5, 6, 7] +2024-12-02 16:25:21,157 - INFO - anteater - work on npu_chip_info_aicore_current_freq, slow_node_detection start. +2024-12-02 16:25:21,584 - INFO - anteater - time_node_compare result: []. +2024-12-02 16:25:21,592 - INFO - anteater - dnscan labels: [0 0 0 0 0 0 0 0] +2024-12-02 16:25:21,594 - INFO - anteater - dnscan labels: [0 0 0 0 0 0 0 0] +2024-12-02 16:25:21,597 - INFO - anteater - dnscan labels: [0 0 0 0 0 0 0 0] +2024-12-02 16:25:21,598 - INFO - anteater - space_nodes_compare result: []. +2024-12-02 16:25:21,598 - INFO - anteater - Time and space aggregated result: []. +2024-12-02 16:25:21,598 - INFO - anteater - work on npu_chip_info_aicore_current_freq, slow_node_detection end. + +2024-12-02 16:25:21,598 - INFO - anteater - Groups-0, metric: npu_chip_roce_tx_err_pkt_num, start detection. +2024-12-02 16:25:21,607 - INFO - anteater - Metric-npu_chip_roce_tx_err_pkt_num single group has data 8. ranks: [0, 1, 2, 3, 4, 5, 6, 7] +2024-12-02 16:25:21,611 - INFO - anteater - work on npu_chip_roce_tx_err_pkt_num, slow_node_detection start. +2024-12-02 16:25:22,040 - INFO - anteater - time_node_compare result: []. +2024-12-02 16:25:22,040 - INFO - anteater - Skip space nodes compare. +2024-12-02 16:25:22,040 - INFO - anteater - Time and space aggregated result: []. +2024-12-02 16:25:22,040 - INFO - anteater - work on npu_chip_roce_tx_err_pkt_num, slow_node_detection end. + +2024-12-02 16:25:22,041 - INFO - anteater - accomplishment: 1/9 +2024-12-02 16:25:22,041 - INFO - anteater - accomplishment: 2/9 +2024-12-02 16:25:22,041 - INFO - anteater - accomplishment: 3/9 +2024-12-02 16:25:22,041 - INFO - anteater - accomplishment: 4/9 +2024-12-02 16:25:22,042 - INFO - anteater - accomplishment: 5/9 +2024-12-02 16:25:22,042 - INFO - anteater - accomplishment: 6/9 +2024-12-02 16:25:22,042 - INFO - anteater - accomplishment: 7/9 +2024-12-02 16:25:22,042 - INFO - anteater - accomplishment: 8/9 +2024-12-02 16:25:22,042 - INFO - anteater - accomplishment: 9/9 +2024-12-02 16:25:22,043 - INFO - anteater - SlowNodeDetector._execute costs 1.83 seconds! +2024-12-02 16:25:22,043 - INFO - anteater - END! ``` -## Output Data +## Exception Detection Output Data -If gala-anteater detects an exception, it sends the result to Kafka. The output data format is as follows: +When gala-anteater detects exceptions, it outputs the results to `model_topic` of Kafka. The output data format is as follows. ```json { - "Timestamp":1659075600000, - "Attributes":{ - "entity_id":"xxxxxx_sli_1513_18", - "event_id":"1659075600000_1fd37742xxxx_sli_1513_18", - "event_type":"app" - }, - "Resource":{ - "anomaly_score":1.0, - "anomaly_count":13, - "total_count":13, - "duration":60, - "anomaly_ratio":1.0, - "metric_label":{ - "machine_id":"1fd37742xxxx", - "tgid":"1513", - "conn_fd":"18" - }, - "recommend_metrics":{ - "gala_gopher_tcp_link_notack_bytes":{ - "label":{ - "__name__":"gala_gopher_tcp_link_notack_bytes", - "client_ip":"x.x.x.165", - "client_port":"51352", - "hostname":"localhost.localdomain", - "instance":"x.x.x.172:8888", - "job":"prometheus-x.x.x.172", - "machine_id":"xxxxxx", - "protocol":"2", - "role":"0", - "server_ip":"x.x.x.172", - "server_port":"8888", - "tgid":"3381701" - }, - "score":0.24421279500639545 - }, - ... - }, - "metrics":"gala_gopher_ksliprobe_recent_rtt_nsec" - }, - "SeverityText":"WARN", - "SeverityNumber":14, - "Body":"TimeStamp, WARN, APP may be impacting sli performance issues." + "Timestamp": 1730732076935, + "Attributes": { + "resultCode": 201, + "compute": false, + "network": false, + "storage": true, + "abnormalDetail": [{ + "objectId": "-1", + "serverIp": "96.13.19.31", + "deviceInfo": "96.13.19.31:8888*-1", + "kpiId": "gala_gopher_disk_wspeed_kB", + "methodType": "TIME", + "kpiData": [], + "relaIds": [], + "omittedDevices": [] + }], + "normalDetail": [], + "errorMsg": "" + }, + "SeverityText": "WARN", + "SeverityNumber": 13, + "is_anomaly": true } ``` + +## Output Fields + +| Field | Type/Unit | Description | +| -------------- | --------- | ----------------------------------------------------------------------------------------------------------------------- | +| Timestamp | ms | Timestamp when the fault was detected and reported | +| resultCode | int | Fault code, with 201 indicating a fault and 200 indicating no fault | +| compute | bool | Whether the fault type is compute | +| network | bool | Whether the fault type is network | +| storage | bool | Whether the fault type is storage | +| abnormalDetail | list | Details of the fault | +| objectId | int | Fault object ID, with -1 indicating a node fault and 0 to 7 indicating specific fault card numbers | +| serverIp | string | IP address of the fault object | +| deviceInfo | string | Detailed fault information | +| kpiId | string | Algorithm type ("TIME" or "SPACE") that detected the fault | +| kpiData | list | Time-series data of the fault (requires enabling a switch, disabled by default) | +| relaIds | list | IDs of normal cards associated with the fault card, indicating normal card numbers compared under the "SPACE" algorithm | +| omittedDevices | list | Card numbers to be ignored in display | +| normalDetail | list | Time-series data of normal cards | +| errorMsg | string | Error message | +| SeverityText | string | Error type ("WARN" or "ERROR") | +| SeverityNumber | int | Error severity level | +| is_anomaly | bool | Whether a fault exists | diff --git a/docs/en/docs/GCC/D-FOT-user-guide.md b/docs/en/docs/GCC/D-FOT-user-guide.md new file mode 100644 index 0000000000000000000000000000000000000000..77fa22f0239082dda716cd86d52f723d93429977 --- /dev/null +++ b/docs/en/docs/GCC/D-FOT-user-guide.md @@ -0,0 +1,158 @@ +# Dynamic Feedback-directed Optimization Tool User Guide + +## Introduction + +D-FOT, the Dynamic Feedback-directed Optimization Tool, enables fully automated and seamless feedback-directed optimization (FDO) for applications, enhancing both usability and performance. The tool supports two types of dynamic optimizations: startup optimization and runtime optimization. Currently, it implements startup optimization using oeAware. + +- Startup optimization: During application execution, D-FOT automatically performs sampling and FDO. Once an application is optimized, D-FOT seamlessly takes over the next startup without requiring user intervention. + +- Runtime optimization: D-FOT automatically conducts sampling and FDO during application runtime without requiring restarts. The process is entirely user-free, and the optimized version is started with minimal disruption. + +## Software Architecture Overview + +D-FOT includes the following modules: + +- Sampling data processing using libkperf +- Startup takeover and binary optimization enabled by sysBoost +- Binary FDO powered by llvm-bolt +- Implementation of dfot_tuner_sysboost, an oeAware tuning plugin + +## Dependencies + +OS requirement: openEuler 22.03 LTS SP4 +The following dependencies can be installed via Yum: + +| Component | Repository | Branch or Version | Description | +| --------------- | --------------------------------------------- | --------------------------------- | ----------------------------------- | +| oeAware-manager | | openEuler-22.03-LTS-SP4 v2.0.0-3 | Online seamless tuning framework | +| libkperf | | openEuler-22.03-LTS-SP4 v1.2-2 | Lightweight in-memory sampling tool | +| sysboost | | openEuler-22.03-LTS-SP4 | Microarchitecture optimization tool | +| llvm-bolt | | openEuler-22.03-LTS-SP4 17.0.6-12 | Binary optimizer | + +## Usage + +### Prerequisites for the Application to be Optimized + +1. The binary file to be optimized must include relocation information. For self-compiled software, add the `-Wl,-q` linking options during compilation. For example, for MySQL: `cmake .. -DCMAKE_INSTALL_PREFIX=/usr/local/mysql -DBUILD_CONFIG=mysql_release -DWITH_BOOST=../boost -DCMAKE_C_LINK_FLAGS="-Wl,-q" -DCMAKE_CXX_LINK_FLAGS="-Wl,-q"`. For openEuler software packages, relocation packages for corresponding applications will be provided in the future for direct installation. +2. To verify if the target binary file includes relocation information: After `-Wl,-q` are used for compilation, the binary file will contain additional `RELA` sections. Use `readelf -SW /path/to/bin` to verify. For example, before MySQL is compiled with `-Wl,-q`, only `.rela.dyn` and `.rela.plt` sections are present in the MySQL binary file. After the options are used, more than 10 `rela` additional sections will appear, including `.rela.text` and `.rela.eh_frame`. If `-Wl,-q` is not applied, warnings will appear during manual perf sampling and execution of `perf2bolt`, or during `llvm-bolt` optimization (regardless of whether the sysBoost mechanism is used): `BOLT-WARNING: non-relocation mode for AArch64 is not fully supported`. + +### D-FOT Preparation + +Install D-FOT via Yum or build from source using the following commands (note that if libkperf or oeAware-manager is also built from source, specify additional `lib` and `include` paths during `cmake` execution): + +```shell +# Install dependencies +yum install boost-devel log4cplus-devel numactl-devel libkperf-devel oeAware-manager-devel +# Download and compile the source code. +git clone https://gitee.com/openeuler/D-FOT.git +cd D-FOT +mkdir build && cd build +cmake ../ -DCMAKE_BUILD_TYPE=RelWithDebInfo -DCMAKE_SKIP_RPATH=TRUE +make -j`nproc` +cd .. + +cp build/libdfot.so /lib64/oeAware-plugin/ +chmod 440 /lib64/oeAware-plugin/libdfot.so +mkdir -p /etc/dfot/ +cp configs/dfot.ini /etc/dfot/ +``` + +### Configuration Modification + +Modify **/etc/dfot/dfot.ini**. Refer to the following descriptions for the configuration items: + +General configuration: `[general]` + +| Item | Value Range | Available | Description | +| ----------------------------- | ----------------------------------- | --------- | ---------------------------------------------------------------------------------------------- | +| LOG_LEVEL | `` | Yes | Log level for the optimization service, in descending order. Lower levels produce more logs. The default is `INFO`. | +| COLLECTOR_SAMPLING_STRATEGY | `0` | No | Sampling strategy:
0: Continuous low-frequency sampling after plugin enablement
1: Monitoring thread initiation upon enablement with sampling triggered by load threshold
Currently, sampling is controlled by oeAware, and only 0 is supported. | +| COLLECTOR_HIGH_LOAD_THRESHOLD | `[0, cpus*100]` | No | Effective only for sampling strategy 1. Uses `HIGH_LOAD_THRESHOLD` as the CPU usage threshold for triggering sampling. This item is currently not supported. | +| COLLECTOR_SAMPLING_PERIOD | `100` | No | Interval for collector execution, in milliseconds. Currently configured by oeAware. | +| COLLECTOR_SAMPLING_FREQ | `100` | No | Sampling frequency. Samples `COLLECTOR_SAMPLING_FREQ` times per second. Currently configured by oeAware. | +| COLLECTOR_DATA_AGING_TIME | Determined by actual needs | Yes | Sampling data aging time in milliseconds. Discards accumulated sampling data when the time difference between current and oldest data exceeds this threshold. | +| TUNER_TOOL | `["sysboost"]` | No | Binary optimizer. Currently, only `sysboost` is supported. | +| TUNER_CHECK_PERIOD | `[10, max]` | Yes | Interval for optimization plugin checks in milliseconds. Determines whether internal collected data meets the conditions for a new round of optimization. No upper limit, but avoid setting it too large to prevent delays. The default is 1000. | +| TUNER_PROFILE_DIR | Determined by actual needs | Yes | Directory for storing sampling data. Profile files are named in format **\[app_name]_\[full_path_hash]_\[threshold].profile**. | +| TUNER_OPTIMIZING_STRATEGY | `[0, 1]` | Yes | Optimization strategy. `0`: One-time optimization. `1`: Continuous optimization as long as sampling information is refreshed. | +| TUNER_OPTIMIZING_CONDITION | `0` | No | Condition for triggering optimization. `0`: Optimization after application exit. `1`: Optimization during low load. `2`: Optimization after application exit and during low load. Currently, only `0` is supported. | + +Application configuration: `[app]` + +| Item | Value Range | Available | Description | +| ----------------------------- | ---------------------------- | --------- | ---------------------------------------------------------------------------------------------- | +| FULL_PATH | Determined by actual needs | Yes | Absolute path of the application binary file. | +| DEFAULT_PROFILE | Determined by actual needs | Yes | Out-of-the-box profile file for the application, used to enable binary optimization during cold start. Leave blank if not available. | +| COLLECTOR_DUMP_DATA_THRESHOLD | `[10000, max]` | Yes | Triggers data export to the profile when the number of sampling data rows reaches this threshold. A larger value requires more samples. This value should be determined based on the actual application and testing scenario. The reference value for MySQL is `65000`. | +| BOLT_DIR | `/usr/bin` | No | Path to the BOLT tool. If this item is not configured, the default value is `/usr/bin`. The tool calls `${BOLT_DIR}/perf2bolt` and `${BOLT_DIR}/llvm-bolt`. Currently, the value is determined by sysBoost. | +| BOLT_OPTIONS | Determined by actual needs | Yes | BOLT optimization options. Configuring this can override the default options for targeted tuning. | +| UPDATE_DEBUG_INFO | `[0, 1]` | Yes | Whether to synchronously update debug information during optimization. `1`: Update. `0`: Do not update. Note: Updating debug information incurs additional time. | + +### Plugin Usage + +See . + +For D-FOT installations via Yum, use the following commands to enable the plugin instances: + +```shell +# Restart the oeaware service. +systemctl restart oeaware +# Enable the sampling collector plugin. +oeawarectl -e pmu_sampling_collector +# Enable the FDO plugin. +oeawarectl -e dfot_tuner_sysboost + +# Disable both plugins. +oeawarectl -d pmu_sampling_collector +oeawarectl -d dfot_tuner_sysboost +``` + +For source-built D-FOT, copy **libdfot.so** to the default plugin directory **/lib64/oeAware-plugin/**, then load and activate the plugin instance. Ensure the plugin permissions are set to 440: + +```shell +# Restart the oeaware service (automatically loads plugins from "/lib64/oeAware-plugin/"). +systemctl restart oeaware +# Alternatively, manually load the plugin without restarting the service. +oeawarectl -l libdfot.so +# Perform subsequent enable operations as described above. +``` + +For additional steps, consult the oeAware user manual. + +### Example Usage + +Use mysql-8.0.25 for TPC-C testing: + +```shell +# 1. Prepare the environment. +yum install libkperf oeaware-manager sysboost llvm-bolt D-FOT + +# 2. Build MySQL. +# "-Wl,-q" is required for optimization. "-fPIE" and "-Wl,-zmax-page-size=0x200000 -Wl,-zcommon-page-size=0x200000" are optional but necessary for sysBoost huge page preloading. +cmake .. -DCMAKE_INSTALL_PREFIX=/usr/local/mysql -DBUILD_CONFIG=mysql_release -DWITH_BOOST=../boost -DCMAKE_C_FLAGS="-fPIE" -DCMAKE_CXX_FLAGS="-fPIE" -DCMAKE_C_LINK_FLAGS="-Wl,-q -Wl,-zmax-page-size=0x200000 -Wl,-zcommon-page-size=0x200000 -pie" -DCMAKE_CXX_LINK_FLAGS="-Wl,-q -Wl,-zmax-page-size=0x200000 -Wl,-zcommon-page-size=0x200000 -pie" + +# 3. Start oeaware and optimization plugins. +# Update "/etc/dfot/dfot.ini" with application-specific details, then run the following commands. +systemctl start sysboost +systemctl start oeaware +oeawarectl -e pmu_sampling_collector +oeawarectl -e dfot_tuner_sysboost + +# 4. Execute TPC-C testing. +... + +# 5. Restart MySQL. +# Check "/etc/dfot/dfot.log" beforehand to confirm optimization. The application will run the optimized version after restarting. +``` + +## Constraints and Limitations + +1. Due to sysBoost limitations, D-FOT is not supported in virtualization scenarios (KVM-based VMs are supported without live migration capability. Docker containers are not supported). +2. The target application must include relocation information for optimization. +3. When D-FOT is used as an oeAware tuning plugin, the pmu_sampling_collector plugin has a fixed sampling frequency of 100, which may result in longer sampling times. (the default for perf is 4000 for comparison). + +## Future Plans + +- [ ] Support for virtualization scenarios +- [ ] Support for runtime optimization +- [ ] Improved binary optimization results diff --git a/docs/en/docs/Gazelle/Gazelle-for-opengauss-acceleration.md b/docs/en/docs/Gazelle/Gazelle-for-opengauss-acceleration.md new file mode 100644 index 0000000000000000000000000000000000000000..419c2000d6316e465ed9b57422c61bf46cfea497 --- /dev/null +++ b/docs/en/docs/Gazelle/Gazelle-for-opengauss-acceleration.md @@ -0,0 +1,484 @@ +# Gazelle for openGauss Acceleration + +## Background + +openGauss is a high-performance database, and Gazelle serves as a high-performance user-space protocol stack that significantly enhances application network I/O throughput. By utilizing Gazelle to accelerate openGauss, the database performance can be substantially improved. Gazelle delivers a 15% performance boost in single-node setups and a 5% improvement in active/standby configurations. + +## Limitations + +- openGauss 6.0.0 (LTS) has been verified. Other versions have not been tested and may not be supported. +- Gazelle has been validated for acceleration in single-node and active/standby scenarios. Other configurations have not been tested and may not be compatible. +- Gazelle does not support port reuse: If a port is occupied on an IP address within the user-space protocol stack, it cannot be used by other IP addresses. + +## User-Space Environment Setup + +### Gazelle Environment Configuration + +Run the following command to check the supported huge page sizes: + +```shell +ll /sys/kernel/mm/hugepages/ +``` + +Typically, each NUMA node requires 2 to 3 GB of huge page memory. With 4 NUMA nodes, this translates to 8 to 12 GB of huge page memory. Configure the number of huge pages based on the supported sizes. + +For instance, to add `hugepages-1048576kB` (1 GB) huge pages, select 20 huge pages, which corresponds to 20 GB of memory. Ensure the number is a multiple of 4. Avoid setting this value too high to prevent excessive OS memory consumption. + +```shell +echo 20 > /sys/kernel/mm/hugepages/hugepages-1048576kB/nr_hugepages + +# After configuration, create a local drive mount. +mkdir /mnt/hugepages-1G +mount -t hugetlbfs -o pagesize=1G nodev /mnt/hugepages-1G + +# Load kernel modules. +modprobe vfio enable_unsafe_noiommu_mode=1 +modprobe vfio-pci +``` + +>![](./public_sys-resources/icon-note.gif) **Note:** +> +>For Gazelle deployment details, refer to the [Gazelle User Guide](https://gitee.com/openeuler/gazelle/blob/master/doc/user-guide.md).
+>For different NIC binding methods in user space, see [Gazelle NIC Support and Usage](https://gitee.com/openeuler/gazelle/blob/master/doc/nic-support.md). + +### lstack.conf Configuration + +Use the database user to write the **lstack.conf** file, ensuring the user has access permissions. + +Key configuration items and modifications: + +- `dpdk_args` + +`3096,3096,3096,3096` sets the memory size for each NUMA node. Here, it is set to 3GB. + +Modify `/mnt/hugepages-1G` to the path set in the huge page environment configuration. + +- `num_cpus` + +`30,31,62,63,94,95,126,127` are the CPU cores assigned for network interrupts. This example uses the last two CPU cores of each NUMA node, totaling eight for interrupts. + +- `app_bind_numa` + +This parameter determines whether epoll/poll threads are bound to their corresponding NUMA nodes. Set it to `0` (no binding). Gazelle and openGauss have conflicting core binding strategies. Therefore, use the core binding strategy of openGauss. + +- `host_addr, mask_addr, gateway_addr, devices` + +Obtain the required NIC IP address information. Typically, use the `ip addr show` command to retrieve this information. `gateway_addr` is usually the IP address with the last octet changed to `1`. Use `route -n` to check the gateway. + +Example NIC configuration: + +- `host_addr`: 20.20.20.119 +- `mask_addr`: 255.255.255.0 +- `gateway_addr`: 20.20.20.1 +- `devices`: 78:b4:6a:40:16:30 + +Example output from `ip addr show`: + +```sh + 8: enp7s0: mtu 1500 qdisc mq state UP group default qlen 1000 + link/ether 78:b4:6a:40:16:30 brd ff:ff:ff:ff:ff:ff + inet 20.20.20.149/24 brd 20.20.20.255 scope global enp7s0 + valid_lft forever preferred_lft forever +``` + +- **app_exclude_cpus** + +Excluded CPU cores. openGauss uses CPU 0 for the xlog write thread. Use `app_exclude_cpus="0"` to exclude CPU 0 from core binding. + +- **listen_shadow** + +Whether to use shadow fd listening. `0` disables it, `1` enables it. Enable this for single listen threads with multiple protocol stack threads. + +Example configuration file: + +```ini +dpdk_args=["--socket-mem", "3096,3096,3096,3096", "--huge-dir", "/mnt/hugepages-1G", "--proc-type", "primary", "--legacy-mem"] + +use_ltran=0 +kni_switch=0 + +low_power_mode=0 + +#needed mbuf count = tcp_conn_count * mbuf_count_per_conn +tcp_conn_count = 1500 +mbuf_count_per_conn = 350 + +# send ring size, default is 32, max is 2048 +send_ring_size = 32 + +# 0: when send ring full, send return +# 1: when send ring full, alloc mbuf from mempool to send data +expand_send_ring = 0 + +#protocol stack thread per loop params +#read data form protocol stack into recv_ring +read_connect_number = 4 +#process rpc msg number +rpc_number = 4 +#read nic pkts number +nic_read_number = 128 + +#each cpu core start a protocol stack thread. +num_cpus="30,31,62,63,94,95,126,127" + +#app worker thread bind to numa in epoll/poll. +app_bind_numa=0 +#app main thread affinity set by dpdk. +main_thread_affinity=0 + +host_addr="20.20.20.119" +mask_addr="255.255.255.0" +gateway_addr="20.20.20.1" +devices="78:b4:6a:40:16:31" + +udp_enable=0 +#0: use rss rule +#1: use tcp tuple rule to specify packet to nic queue +tuple_filter=0 + +#tuple_filter=1, below cfg valid +num_process=1 +process_numa="0,1" +process_idx=0 + +#tuple_filer=0, below cfg valid +listen_shadow=1 +#exclude cpu +app_exclude_cpus="0" +``` + +## Privilege Escalation + +Elevate privileges for the **gaussdb** binary, **liblstack.so**, and the `ls` command. + +```shell +# Elevate privileges for the gaussdb binary. +sudo setcap 'cap_chown,cap_dac_override,cap_dac_read_search,cap_sys_rawio,cap_net_admin,cap_net_raw,cap_sys_admin+eip' `which gaussdb` +# Elevate privileges for liblstack.so. +sudo chmod u+s /usr/lib64/liblstack.so +# Elevate privileges for the ls command. +setcap 'cap_chown,cap_dac_override,cap_dac_read_search,cap_sys_rawio,cap_net_admin,cap_net_raw,cap_sys_admin+eip' $(which ls) +``` + +After privilege escalation, **gaussdb** will no longer search for dynamic library paths from `LD_LIBRARY_PATH`. Therefore, configure the global dynamic library path: **vim /etc/ld.so.conf.d/opengauss.conf**. Add the actual dynamic library path. + +```text +/home/code/openGauss-server/dest/lib +``` + +## Required Path Permissions + +Modify the permissions for the huge page memory file path and **liblstack.so** to allow user access. + +```shell +chown -R 777 /mnt/ +chmod 777 /usr/lib64/liblstack.so +``` + +Ensure the **lstack.conf** file also allows user access. + +## Database Testing + +### Preparing Necessary Information + +For database testing, at least one NVME drive is required for data storage. + +Local testing uses an HINIC NIC. + +Some information can be queried using the following commands, assuming the NIC name is `enp8s0`. + +```shell +# PCI query: +ethtool -i enp8s0 | grep bus-info +``` + +### Switching to the User-Space NIC + +This operation will render the NIC unusable. Use a BMC machine or an environment with dual network ports. Otherwise, the environment will become unavailable. +Switch the NIC to user-space mode using the **root** user. This operation will stop the NIC and take over with DPDK. If the NIC is used for an SSH connection, the connection will be terminated. + +```shell +#PCI=0000:08:00.0 +#NET_DEVICE=enp8s0 +ifconfig enp8s0 down +sudo modprobe vfio enable_unsafe_noiommu_mode=1 +sudo echo 1 > /sys/module/vfio/parameters/enable_unsafe_noiommu_mode +sudo dpdk-devbind -b vfio-pci 0000:08:00.0 +``` + +### Starting the Database + +Modify the openGauss configuration file: + +- Append parameters to the openGauss database configuration file **postgresql.conf**. +- Modify the **postgresql.conf** file according to the actual situation, adjusting thread pool parameters and adding performance parameters to the configuration file. + +```shell +# This parameter specifies the number of CPUs bound to openGauss. For example, if openGauss is bound to CPUs 1 to 29, 32 to 61, 64 to 93, and 96 to 125 across 4 NUMA nodes (119 CPUs), the thread count should be an integer multiple of the CPU count, such as 476. +thread_pool_attr = '476,4,(cpubind:1-29,32-61,64-93,96-125)' + +# Enable this parameter when to use Gazelle for acceleration. +enable_gazelle_performance_mode=on +``` + +Environment cleanup: + +To avoid interference from background caches and semaphores, clean up the corresponding data. + +```shell +ipcs -m | awk '$2 ~/[0-9]+/ {print $2}' | while read s; do ipcrm -m $s; done +ipcs -s | awk '$2 ~/[0-9]+/ {print $2}' | while read s; do ipcrm -s $s; done +echo 3 > /proc/sys/vm/drop_caches +``` + +Start the database: + +```shell +# Set the Gazelle configuration file path. +LSTACK_CONF_PATH=/usr1/gazelle/gazelle_conf/lstack.conf +# Start Gazelle-accelerated gaussdb, using the openGauss dn1 database node as an example. +LD_PRELOAD=liblstack.so GAZELLE_BIND_PROCNAME=gaussdb LSTACK_CONF_PATH=$LSTACK_CONF_PATH /home/opengauss/software/openGauss/bin/gaussdb -D /home/opengauss/software/openGauss/data/dn1 +``` + +### Starting TPC-C Testing + +The client needs to configure network interrupts based on the actual situation. Here, we configure 20 interrupts as an example. The corresponding **bind_irq.sh** file is as follows: + +```shell +intf=enp4s0 + +ethtool -G ${intf} rx 1024 tx 1024 +ethtool -K ${intf} lro on +ethtool -L ${intf} combined ${combined} + +irq_list=`cat /proc/interrupts | grep $intf | awk {'print $1'} | tr -d ":"` +irq_array_net=($irq_list) + +cpu_array_irq=(27 28 29 30 31 59 60 61 62 63 91 92 93 94 95 123 124 125 126 127) + +for (( i=0;i<20;i++)) +do + echo "${cpu_array_irq[$i]}" > /proc/irq/${irq_array_net[$i]}/smp_affinity_list +done + +for j in ${irq_array_net[@]} +do + cat /proc/irq/$j/smp_affinity_list +done +``` + +The benchmark client needs to adjust the concurrency based on the actual situation. +Typically, modify it to a multiple of the CPU count specified in the `cpubind` parameter in the **postgresql.conf** file. For example, if the CPU count is 119 (1 to 29, 32 to 61, 64 to 93, 96 to 125), multiply by 4 to get 714, and set the concurrency to 714: + +```ini +terminals=714 +``` + +### Restoring Configurations + +1. Stop the database. +2. Use the **root** user to switch the NIC back to kernel mode. + +```shell +#PCI=0000:08:00.0 +#NET_DEVICE=enp8s0 +#IP=20.20.20.119 +sudo dpdk-devbind -u 0000:08:00.0 +sudo dpdk-devbind -b hinic 0000:08:00.0 +sudo ifconfig enp8s0 20.20.20.119 netmask 255.255.255.0 +``` + +### Test Conclusion + +In single-node testing, the measured TPC-C performance improvement is approximately 15%. + + + +## openGauss Configuration File Example + +Open the **postgresql.conf** file, append the following content at the end of the file (replace the IP address with the actual IP address): + +```shell +max_connections = 4096 +allow_concurrent_tuple_update = true +audit_enabled = off +checkpoint_segments = 1024 +checkpoint_timeout = 15min +cstore_buffers = 16MB +enable_alarm = off +enable_codegen = false +enable_data_replicate = off +full_page_writes = off +max_files_per_process = 100000 +max_prepared_transactions = 2048 +shared_buffers = 350GB +#max_process_memory = 100GB +use_workload_manager = off +wal_buffers = 1GB +work_mem = 1MB +log_min_messages = FATAL +transaction_isolation = 'read committed' +default_transaction_isolation = 'read committed' +synchronous_commit = on +fsync = on +maintenance_work_mem = 2GB +vacuum_cost_limit = 10000 +autovacuum = on +autovacuum_mode = vacuum +autovacuum_max_workers = 20 +autovacuum_naptime = 5s +autovacuum_vacuum_cost_delay = 10 +#xloginsert_locks = 48 +update_lockwait_timeout = 20min + +enable_mergejoin = off +enable_nestloop = off +#----- +enable_hashjoin = off +#enable_cbm_tracking = off +enable_bitmapscan = on +enable_material = off + +wal_log_hints = off +log_duration = off +checkpoint_timeout = 15min +autovacuum_vacuum_scale_factor = 0.1 +autovacuum_analyze_scale_factor = 0.02 +enable_save_datachanged_timestamp = false + +# enable_stat_send = off +# enable_commandid_send = off +log_timezone = 'PRC' +timezone = 'PRC' +lc_messages = 'C' +lc_monetary = 'C' +lc_numeric = 'C' +lc_time = 'C' + +enable_thread_pool = on + +enable_double_write = on + +enable_incremental_checkpoint = on +enable_opfusion = on +instr_unique_sql_count=0 +advance_xlog_file_num = 100 +numa_distribute_mode = 'all' + +track_activities = off +enable_instr_track_wait = off +enable_instr_rt_percentile = off +track_counts = off +track_sql_count = off +enable_instr_cpu_timer = off + +plog_merge_age = 0 + +# numa_excluded_cpus = '29,30,31,61,62,63,93,94,95,125,126,127' +# numa_excluded_cpus = '28,29,30,31,60,61,62,63,92,93,94,95,124,125,126,127' + +#enable_crc_check = off +session_timeout = 0 + +enable_instance_metric_persistent = off +enable_logical_io_statistics = off +enable_page_lsn_check = off +enable_user_metric_persistent = off +enable_xlog_prune = off + +enable_resource_track = off +instr_unique_sql_count=0 + +remote_read_mode = non_authentication +client_min_messages = ERROR +log_min_messages = FATAL +enable_asp = off +enable_bbox_dump = off +bgwriter_flush_after = 32 +#gs_clean_timeout = '300s' +#minimum_pool_size = 200 +wal_keep_segments = 1025 + + +#scan_fusion +enable_bitmapscan = off +enable_seqscan = off + +track_activities='off' +enable_resource_track='off' +enable_instr_rt_percentile='off' +enable_instr_cpu_timer='off' +# bypass_workload_manager='off' +enable_asp='off' + +enable_thread_pool = on +xloginsert_locks=16 +checkpoint_segments=8000 + +enable_stmt_track=false + +data_replicate_buffer_size=128MB + +#bgwriter_thread_num = 1 + +bgwriter_delay = 5s +incremental_checkpoint_timeout = 5min +pagewriter_thread_num = 2 +candidate_buf_percent_target = 0.3 +pagewriter_sleep = 100ms + +standby_shared_buffers_fraction = 0.9 + +#replconninfo1 = 'localhost=20.20.20.58 localport=21131 localheartbeatport=21135 localservice=21134 remotehost=20.20.20.64 remoteport=21131 remoteheartbeatport=21135 remoteservice=21134' + +# 2020-12-20 +enable_incremental_checkpoint = on +checkpoint_segments = '4096' +checkpoint_timeout = 50min +#enable_thread_pool = off + +max_process_memory = 240GB +shared_buffers = 180GB + +wal_level = archive +hot_standby = off + +wal_receiver_buffer_size = 256MB +walsender_max_send_size = 32MB + + +# 2021-03-16 +xloginsert_locks = 8 +wal_file_init_num = 30 +#xlog_idle_flushes_before_sleep = 500000000 +walwriter_sleep_threshold = 50000 +wal_writer_delay = 150 + +undo_zone_count = 0 + +walwriter_cpu_bind = 0 +checkpoint_segments = 32768 + +local_syscache_threshold = 16MB +enable_cachedplan_mgr = off +enable_global_syscache = off + +time_record_level = 1 +enable_beta_opfusion = on + +#wal_file_init_num = 10000 +#advance_xlog_file_num = 50000 +light_comm = on +enable_indexscan_optimization = on + +hot_standby = off + +checkpoint_segments = 3000 +advance_xlog_file_num = 100000 +thread_pool_attr = '476,4,(cpubind:1-29,32-61,64-93,96-125)' +enable_gazelle_performance_mode=on + +#------------------------------------------------------------------------------ +wal_file_init_num = 40000 +advance_xlog_file_num = 100000 +``` diff --git a/docs/en/docs/Gazelle/Gazelle-for-redis-acceleration.md b/docs/en/docs/Gazelle/Gazelle-for-redis-acceleration.md new file mode 100644 index 0000000000000000000000000000000000000000..5450612b7fd3ed6ce5fa54cfb6d03d1f12597e12 --- /dev/null +++ b/docs/en/docs/Gazelle/Gazelle-for-redis-acceleration.md @@ -0,0 +1,345 @@ +# Gazelle for Redis Acceleration + +## Background + +Gazelle is a high-performance user-space protocol stack. It directly processes network packets in user space using DPDK, transmits packets through shared huge pages memory, and implements a lightweight LwIP stack. It significantly improves application network I/O throughput, focusing particularly on database network performance acceleration for systems like MySQL and Redis. + +Gazelle shows notable performance improvements compared to the kernel protocol stack in Redis testing. For example, in tests conducted on an Arm platform with 8 cores, 32 GB memory, and OVS+DPDK VM, with 1,000 connections and a default packet size of 3, the results show approximately 1.7x improvement for `set` operations and 1.5x improvement for `get` operations. + +```sh +# Kernel +redis-benchmark -h 192.168.1.127 -p 6379 -c 1000 -n 10000000 -r 10000000 -t set,get --threads 12 +# set +Summary: + throughput summary: 132402.98 requests per second + latency summary (msec): + avg min p50 p95 p99 max + 7.474 1.376 7.207 9.399 14.255 30.879 +# get +Summary: + throughput summary: 142834.69 requests per second + latency summary (msec): + avg min p50 p95 p99 max + 6.919 1.384 6.663 8.751 13.311 24.207 +``` + +```sh +# Gazelle +redis-benchmark -h 192.168.1.127 -p 6379 -c 1000 -n 10000000 -r 10000000 -t set,get --threads 12 +# set +Summary: + throughput summary: 359389.03 requests per second + latency summary (msec): + avg min p50 p95 p99 max + 2.736 0.240 2.735 2.895 3.127 9.471 +# get +Summary: + throughput summary: 359401.97 requests per second + latency summary (msec): + avg min p50 p95 p99 max + 2.752 0.488 2.751 2.903 3.135 16.671 +``` + +>![](./public_sys-resources/icon-note.gif) **Note:** +>Performance improvements may vary depending on hardware configuration and network environment. The test results above are for reference only. + +## Limitations + +- Only IPv4 is supported. +- Maximum concurrent connections is 20,000 +- Multiple Gazelle processes on a single node are not supported. (Multiple Redis servers cannot be started with Gazelle on one node.) +- In Redis master-slave clusters, kernel-space logs repeatedly show master-slave reconnection messages while user-space logs show it only once. This is normal behavior without functional impact. When a kernel-space master node goes offline, slave nodes attempt to connect by sending SYN packets. The master node in TIME_WAIT state responds with RST packets to close connections, creating a loop. When a user-space master node goes offline, Gazelle+Redis connections close completely without entering TIME_WAIT state. SYN packets from slave nodes receive no RST response, resulting in one connection showing SYN_SENT status when checked with `gazellectl lstack show ip -c`. + +## Test Procedures + +### Environment Requirements + +#### Hardware + +- Single-node testing: One server and one client +- Master-slave mode: Minimum two servers (master and slave) and one client +- Sentinel mode: Minimum two Redis servers (master and slave), two sentinel servers, and one client +- Cluster mode: Minimum six Redis servers (three masters, three slaves) and one client + +#### Software + +Download the [Redis package](https://download.redis.io/releases/), using Redis version 6.2.9. + +### Server Deployment + +#### Disabling Test Impact Items + +```sh +# Disable firewalls. +systemctl stop iptables +systemctl stop firewalld +``` + +#### Compiling and Installing Redis + +```sh +tar zxvf redis-6.2.9.tar.gz +cd redis-6.2.9/ +make clean +make -j 32 +make install +``` + +#### Setting up the Gazelle Runtime Environment + +- Install Gazelle and dependencies. + +```sh +yum -y install gazelle dpdk libconfig numactl libboundscheck libcap +``` + +- Configure the following parameters in **/etc/gazelle/lstack.conf** (keep other settings at default). + +| Parameter | Value | Description | +| ------------------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| dpdk_args | \["--socket-mem", "2400,0,0,0", "--huge-dir", "/mnt/hugepages-lstack", "--proc-type", "primary"] | Sets 2400 MB memory for CPU/NIC NUMA (adjustable for concurrency). Configure both NUMA nodes if the CPU and NIC are separate. MLX NICs need additional **"-d", "librte_net_mlx5.so"** | +| num_cpus | "2" | Binds lstack to one CPU | +| mbuf_count_per_conn | 34 | Required mbufs per connection | +| tcp_conn_count | 20000 | Maximum Redis test concurrent connections | + +```sh +# Server huge page allocation +mkdir -p /mnt/hugepages-lstack +chmod -R 700 /mnt/hugepages-lstack +mount -t hugetlbfs nodev /mnt/hugepages-lstack -o pagesize=2M # Do not repeat this operation to avoid unreleasable huge page allocation. +echo 2048 > /sys/devices/system/node/node0/hugepages/hugepages-2048kB/nr_hugepages # Select a page size as needed. +cat /sys/devices/system/node/node0/hugepages/hugepages-2048kB/free_hugepages # Check available huge pages on the node. + +# Load kernel modules on the server (skip for MLX NICs) +modprobe vfio enable_unsafe_noiommu_mode=1 +modprobe vfio-pci + +# Bind NIC to user space on the server (skip for MLX NICs) +ip link set enp4s0 down +dpdk-devbind -b vfio-pci enp4s0 + +# Gazelle deployment complete, waiting for application deployment +``` + +> ![](./public_sys-resources/icon-note.gif) **Note:** +> For complete deployment instructions, refer to the [Gazelle User Guide](https://gitee.com/openeuler/gazelle/blob/master/doc/user-guide.md) +> For NIC-specific user space binding instructions, see [Gazelle NIC Support and Usage](https://gitee.com/openeuler/gazelle/blob/master/doc/nic-support.md) + +#### Redis Server Deployment + +Redis supports four deployment modes: single-node, master-slave, sentinel, and cluster configurations. Regardless of the deployment mode, every Redis server requires these basic configurations in its redis.conf file: + +```sh +# Disable protection mode. +protected-mode no +# Gazelle does not support background operation with this parameter. +daemonize no +# Enable AOF persistence (optional for single-node Redis testing). +appendonly yes +``` + +##### Redis Single-Node Deployment + +For a Redis single-node setup, deploy Gazelle and Redis, then start the service. + +```sh +LD_PRELOAD=/usr/lib64/liblstack.so GAZELLE_BIND_PROCNAME=redis-server redis-server /root/redis-6.2.9/redis.conf +``` + +##### Redis Master-Slave Deployment + +Redis master-slave replication creates a one-way data flow from a master node to one or more slave nodes. This configuration requires at least two servers and can be set up using either of these methods: + +- Method 1: + Configure the slave node by adding this line to its redis.conf file, then launch both nodes: + + ```sh + # Replace with master node IP address and port. + slaveof 192.168.1.127 6379 + ``` + + ```sh + LD_PRELOAD=/usr/lib64/liblstack.so GAZELLE_BIND_PROCNAME=redis-server redis-server /root/redis-6.2.9/redis.conf + ``` + +- Method 2: + Start both Redis servers with basic configuration, then establish the master-slave relationship using Redis CLI: + + ```sh + redis-cli -h 192.168.1.127 slaveof NO ONE # For master node + redis-cli -h 192.168.1.128 slaveof 192.168.1.127 6379 # For slave node + ``` + + Verify replication status: + + ```sh + [root@openEuler redis-6.2.9]# redis-cli -h 192.168.1.127 info Replication + # Replication + role:master + connected_slaves:1 + slave0:ip=192.168.1.128,port=6379,state=online,offset=780,lag=0 + ...... + ``` + + ```sh + [root@openEuler redis-6.2.9]# redis-cli -h 192.168.1.128 info Replication + # Replication + role:slave + master_host:192.168.1.127 + master_port:6379 + master_link_status:up + ...... + ``` + +##### Redis Sentinel Deployment + +Sentinel mode enhances master-slave replication by introducing automated monitoring and fault handling through sentinel nodes. This addresses a key limitation of traditional master-slave setups, where server failures require manual intervention to promote a slave to master—a process that is both time-consuming and causes service interruption. For testing Redis sentinel mode, you need at least two Redis servers and two sentinel servers. + +- Set up two Redis servers in master-slave configuration. +- Install Redis on both sentinel servers and configure their **sentinel.conf** files. + +```sh +protected-mode no # Disable protection mode. +daemonize yes # Run in background and log to logfile. +logfile "/var/log/sentinel.log" # Specify log file path. +sentinel monitor mymaster 192.168.1.127 6379 1 # Set the master node name as mymaster and monitor master IP address and port. 1 means one sentinel must agree for failover. +sentinel down-after-milliseconds mymaster 30000 # Time period to determine server failure, defaulting to 30000 ms (30s). +sentinel failover-timeout mymaster 50000 # Maximum timeout for a failed node is 50000 ms. +``` + +- Start Redis sentinel in kernel mode and verify its status. + +```sh +[root@openEuler redis-6.2.9]#redis-sentinel sentinel.conf +[root@openEuler redis-6.2.9]#ps -ef|grep redis-sentinel +root 5961 1 0 13:36 ? 00:00:00 redis-sentinel *:26379 [sentinel] +[root@openEuler redis-6.2.9]#redis-cli -p 26379 info sentinel +# Sentinel +sentinel_masters:1 +sentinel_tilt:0 +sentinel_running_scripts:0 +sentinel_scripts_queue_length:0 +sentinel_simulate_failure_flags:0 +master0:name=mymaster,status=ok,address=192.168.1.127:6379,slaves=2,sentinels=3 +``` + +> ![](./public_sys-resources/icon-note.gif) **Note:** +> Redis server and sentinel must run on separate nodes for proper failover operation. +> Redis sentinel does not support user-space operation + +##### Redis Cluster Deployment + +A Redis cluster enhances the limited concurrency of a single node by enabling data sharing across multiple nodes. The minimum setup requires six Redis servers. + +- Configure **redis.conf** on each server. + +```sh +protected-mode no # Disable protection mode. +daemonize no # Run in foreground. +bind 0.0.0.0 +port 6379 # Use different IP addresses per VM and the default port. +appendonly yes # Enable AOF persistence. +cluster-enabled yes # Enable cluster mode. +cluster-config-file nodes.conf # Auto-maintained configuration file +cluster-node-timeout 5000 # Node heartbeat timeout +``` + +- Launch Redis on all six servers. + +```sh +LD_PRELOAD=/usr/lib64/liblstack.so GAZELLE_BIND_PROCNAME=redis-server redis-server /root/redis-6.2.9/redis.conf +``` + +- Initialize the cluster and confirm node assignments. + +```sh +[root@openEuler redis-6.2.9]# redis-cli --cluster create --cluster-replicas 1 192.168.1.127:6379 192.168.1.128:6379 192.168.1.129:6379 192.168.1.130:6379 192.168.1.131:6379 192.168.1.132:6379 +>>> Performing hash slots allocation on 6 nodes... +...... +Can I set the above configuration? (type 'yes' to accept): yes +>>> Nodes configuration updated +>>> Assign a different config epoch to each node +>>> Sending CLUSTER MEET messages to join the cluster +Waiting for the cluster to join +... +>>> Performing Cluster Check (using node 192.168.1.127:6379) +...... +[OK] All nodes agree about slots configuration. +>>> Check for open slots... +>>> Check slots coverage... +[OK] All 16384 slots covered. # Successful when hash slots are allocated + +# Command explanation: "--cluster-replicas 1" sets one replica per master +# Masters are determined by: total nodes/(replicas + 1) +``` + +- Monitor cluster status from any active node. + +```sh +# Check cluster health. +[root@openEuler redis-6.2.9]# redis-cli -h 192.168.1.127 cluster info +cluster_state:ok # Check hash slot allocation if the value is "fail". +cluster_slots_assigned:16384 +cluster_slots_ok:16384 +cluster_slots_pfail:0 +cluster_slots_fail:0 +...... +``` + +```sh +# View cluster topology. +[root@openEuler redis-6.2.9]# redis-cli -h 192.168.1.128 cluster nodes +514b35aaa5035d489b60a0e8f8fb01d1c20734ce 192.168.1.129:6379@16379 slave 50aa44a1e4a6a0c75cf2f9b20055bfaa77d1b163 0 1724919619916 1 connected +50aa44a1e4a6a0c75cf2f9b20055bfaa77d1b163 192.168.1.127:6379@16379 master - 0 1724919617960 1 connected 0-5460 +a94402ca747ead08e4b93ff975dfbe995068ecbf 192.168.1.130:6379@16379 slave 0a569e1ac4e373a22abcbf6ce6b8118fba3d4d6e 0 1724919618000 3 connected +8c4040a4fa8456044acad2518dc45b8236ba44c4 192.168.1.128:6379@16379 myself,slave 44a96161651c8383fb4966c6dde45d400fe2a203 0 1724919617000 2 connected +0a569e1ac4e373a22abcbf6ce6b8118fba3d4d6e 192.168.1.132:6379@16379 master - 0 1724919618975 3 connected 10923-16383 +44a96161651c8383fb4966c6dde45d400fe2a203 192.168.1.131:6379@16379 master - 0 1724919619617 2 connected 5461-10922 +# Nodes 127, 131, and 132 are masters. Nodes 128, 129, and 130 are slaves. Node IDs link slaves to their masters. +``` + +### Redis Benchmark Tool Deployment on the Client + +- Compilation and installation + +The redis-benchmark utility is included with Redis. Install it by compiling Redis as you did for the server. + +- Testing + +```sh +# For standalone, master-slave, and sentinel modes +# set,get operations +redis-benchmark -h 192.168.1.127 -p 6379 -c 1000 -n 10000000 -d 3 -r 10000000 -t set,get --threads 12 +# Options: +# -h: server address +# -p: server port +# -c: concurrent connections +# -n: total requests +# -t: commands to test +# -d: payload size +# Note: Slave nodes only process get commands in master-slave and sentinel modes due to read-only configuration. +``` + +```sh +# For cluster mode +# set,get operations +redis-benchmark -h 192.168.1.127 -p 6379 -c 1000 -n 10000000 -d 3 -r 10000000 -t set,get --threads 12 --cluster +# Any active cluster node can be specified with -h. +``` + +### Success Indicators for Gazelle-accelerated Redis + +```sh +[root@openEuler redis-6.2.9]# LD_PRELOAD=/usr/lib64/liblstack.so GAZELLE_BIND_PROCNAME=redis-server redis-server redis.conf +LSTACK[2555459]: LD_PRELOAD ok +dpdk argv: --socket-mem 2400,0,0,0 --huge-dir /mnt/hugepages-lstack --proc-type primary +LSTACK[2555459]: cfg_init success +# DPDK startup logs vary by environment. +...... +# Success indicated by these messages +LSTACK: gazelle_stack_thread:533 stack_00 init success +LSTACK: gazelle_network_init:328 gazelle_network_init success +# Standard Redis startup logs follow. +``` + +Verify the deployment by pinging the user-space IP address from **lstack.conf**. A successful ping confirms that Gazelle acceleration is working. diff --git a/docs/en/docs/Gazelle/Gazelle-single-nic-user-guide.md b/docs/en/docs/Gazelle/Gazelle-single-nic-user-guide.md new file mode 100644 index 0000000000000000000000000000000000000000..d2ef0c13eed2bd81d523281165c9e5366a82f5e2 --- /dev/null +++ b/docs/en/docs/Gazelle/Gazelle-single-nic-user-guide.md @@ -0,0 +1,184 @@ +# Gazelle Single-NIC User Guide + +## Overview + +Gazelle currently limits packet processing to application port traffic, leaving maintenance-related packets (like SSH traffic) unprocessed by the acceleration framework. + +### Core Functionality + +Gazelle implements intelligent traffic distribution for all incoming NIC packets. The system routes packets through two channels: + +- Registered port traffic flows through Gazelle's acceleration pipeline. +- Unregistered port traffic routes directly to the kernel. + +Example: In a Redis deployment, Gazelle monitors port 6379. All traffic targeting this port routes through Gazelle's acceleration layer, while remaining traffic flows to the kernel stack. + +### Usage Instructions + +#### VM Scenario + +1. Install DPDK and Gazelle and configure huge pages. + + ```shell + yum install -y dpdk gazelle + echo 1024 > /sys/devices/system/node/node0/hugepages/hugepages-2048kB/nr_hugepages + mkdir -p /mnt/hugepages-lstack + chmod -R 700 /mnt/hugepages-lstack + mount -t hugetlbfs nodev /mnt/hugepages-lstack + ``` + +2. Bind a NIC using DPDK. + + Example of binding a NIC with igb_uio: + + ```shell + cd /lib/modules + my_var=$(find /lib/modules/ -name igb_uio.ko) + modprobe uio + # Load the .ko file. + insmod ${my_var} + # Use igb_uio. + dpdk-devbind -b igb_uio enp3s0 + ``` + +3. Modify the Gazelle configuration file. + + ```shell + flow_bifurcation=1 # Enable the flow bifurcation switch. + ``` + +4. Accelerate applications by launching Gazelle (using Redis as an example). + + ```shell + LD_PRELOAD=/usr/lib64/liblstack.so Gazelle_BIND_PROCNAME=redis-server /root/redis-server /root/redis.conf + ``` + +#### Container Scenario + +1. Install DPDK, configure huge pages, and bind a NIC as described in the VM scenario. +2. Install Docker. + + ```shell + yum install -y docker + ``` + +3. Import an image. + + ```shell + docker load -i openEuler-docker.x86_64.tar.xz + ``` + +##### Host Mode + +1. Launch a container. + + ```shell + docker run -d -it --privileged -v /lib/modules:/lib/modules -v /mnt:/mnt -v /dev:/dev -v /sys/bus/pci/drivers:/sys/bus/pci/drivers -v /sys/kernel/mm/hugepages:/sys/kernel/mm/hugepages -v /sys/devices/system/node:/sys/devices/system/node -v /dev:/dev openeuler-22.03-lts-sp4 bash + ``` + + ```shell + docker # File mapping explanations + -v /lib/modules:/lib/modules # Maps kernel modules. + -v /mnt:/mnt # Maps external storage devices file system. + -v /dev:/dev # Maps kernel devices. + -v /sys/bus/pci/drivers:/sys/bus/pci/drivers # Maps driver files. + -v /sys/kernel/mm/hugepages:/sys/kernel/mm/hugepages # Maps huge page information. + -v /sys/devices/system/node:/sys/devices/system/node # Maps node information. + ``` + +2. Enter the container. + + ```shell + docker exec -it xxxxx bash + ``` + +3. Install DPDK and Gazelle. + + ```shell + yum install -y dpdk gazele + ``` + +4. Modify the configuration file. + + ```shell + flow_bifurcation=1 # Enable the flow bifurcation switch. + devices="52:54:00:de:2a:57" # Modify MAC address to the DPDK-bound NIC address. + ``` + +5. Launch Gazelle (using Redis as an example). + + ```shell + LD_PRELOAD=/usr/lib64/liblstack.so Gazelle_BIND_PROCNAME=redis-server /root/redis-server /root/redis.conf + ``` + +##### VF Passthrough Mode + +1. Launch container. + + ```shell + docker run -d -it --network host --privileged -v /lib/modules:/lib/modules -v \ + /mnt:/mnt -v /dev:/dev -v /sys/bus/pci/drivers:/sys/bus/pci/drivers -v \ + /sys/kernel/mm/hugepages:/sys/kernel/mm/hugepages -v \ + /sys/devices/system/node:/sys/devices/system/node -v /dev:/dev \ + openeuler-22.03-lts-sp4 bash + ``` + +2. Configure a VF passthrough NIC. + + ```shell + echo 2 > /sys/class/net/enp130s0f1/device/sriov_numvfs + docker ps + PID=$(docker inspect -f '{{.State.Pid}}' 容器名称) + mkdir -p /var/run/netns + ln -s /proc/PID/ns/net /var/run/netns/PID + ip link set enp129s0f1v0 netns PID + ``` + +3. Enter the container. + + ```shell + docker exec -it xxx bash + ``` + +4. Install DPDK and Gazelle. + + ```shell + yum install -y dpdk gazele + ``` + +5. Modify the configuration file. + + ```shell + flow_bifurcation=1 # Enable the flow bifurcation switch. + devices="52:54:00:de:2a:57" # Modify MAC address to the VF passthrough NIC address. + ``` + +6. Launch Gazelle (using Redis as an example). + + ```shell + LD_PRELOAD=/usr/lib64/liblstack.so Gazelle_BIND_PROCNAME=redis-server /root/redis-server /root/redis.conf + ``` + +### Technical Limitations + +1. Node-local communication supports TCP only when user-space and kernel endpoints are mixed. +2. Gazelle is incompatible with KNI functionality. +3. Portless packet traffic cannot be distributed. +4. Performance impact is about 2%. +5. The `ip a` command must be supported in virtual/container environments for proper IPv6 functionality. + +### Compatible Management Commands + +- Network utilities: `ifconfig`, `tcpdump` +- Transfer protocols: `ftp`, `sftp` +- Monitoring tools: `sar`, `netstat` +- Remote access: `ssh` (requires explicit service activation as follows) + + ```shell + [root@eb2936ebeaaf ~]# yum install openssh-server + [root@eb2936ebeaaf ~]# vim /etc/ssh/sshd_config + Port 22 # Open the port. + PubkeyAuthentication yes # Modify the authentication method. + [root@eb2936ebeaaf ~]# /usr/sbin/sshd # Start the sshd service. + [root@eb2936ebeaaf ~]# netstat -pant | grep sshd # Check whether sshd is started. + ``` diff --git a/docs/en/docs/Gazelle/Gazelle.md b/docs/en/docs/Gazelle/Gazelle.md index 7b0debf1d63aea44f73cafeb60711d68be3cf2aa..072effd8f99600a15332c544626fe76c97184c85 100644 --- a/docs/en/docs/Gazelle/Gazelle.md +++ b/docs/en/docs/Gazelle/Gazelle.md @@ -143,12 +143,13 @@ GAZELLE_BIND_PROCNAME=test LD_PRELOAD=/usr/lib64/liblstack.so ./test |Options|Value|Remarks| |:---|:---|:---| |dpdk_args|--socket-mem (mandatory)
--huge-dir (mandatory)
--proc-type (mandatory)
--legacy-mem
--map-perfect
-d|DPDK initialization parameter. For details, see the DPDK description.
**--map-perfect** is an extended feature. It is used to prevent the DPDK from occupying excessive address space and ensure that extra address space is available for lstack.
The **-d** option is used to load the specified .so library file.| +|dpdk_args|--socket-mem (mandatory)
--huge-dir (mandatory)
--proc-type (mandatory) -d
"--vdev","net_af_xdp,iface=ipvlan0,queue_count=1"|DPDK initialization parameter. For details, see the DPDK description.
The **-d** option loads the specified .so library file.
**net_af_xdp,iface=ipvlan0,queue_count=1** enables native XDP mode to intercept network traffic and forward packets to userspace. **ipvlan0** specifies the network interface where XDP will handle traffic.| |listen_shadow| 0/1 | Whether to use the shadow file descriptor for listening. This function is enabled when there is a single listen thread and multiple protocol stack threads.| |use_ltran| 0/1 | Whether to use ltran.| |num_cpus|"0,2,4 ..."|IDs of the CPUs bound to the lstack threads. The number of IDs is the number of lstack threads (less than or equal to the number of NIC queues). You can select CPUs by NUMA nodes.| |low_power_mode|0/1|Whether to enable the low-power mode. This parameter is not supported currently.| |kni_switch|0/1|Whether to enable the rte_kni module. The default value is **0**. This module can be enabled only when ltran is not used.| -|flow_bifurcation|0/1 |flow bifurcation switch, transfer ports that Gazelle is not listening to the kernel for processing, default to 0 | +|flow_bifurcation|0/1 |Flow bifurcation switch, which transfers ports that Gazelle is not listening to the kernel for processing, defaulting to 0. | |unix_prefix|"string"|Prefix string of the Unix socket file used for communication between Gazelle processes. By default, this parameter is left blank. The value must be the same as the value of **unix_prefix** in **ltran.conf** of the ltran process that participates in communication, or the value of the **-u** option for `gazellectl`. The value cannot contain special characters and can contain a maximum of 128 characters.| |host_addr|"192.168.xx.xx"|IP address of the protocol stack, which is also the IP address of the application.| |mask_addr|"255.255.xx.xx"|Subnet mask.| @@ -160,6 +161,8 @@ GAZELLE_BIND_PROCNAME=test LD_PRELOAD=/usr/lib64/liblstack.so ./test |rpc_number|4|Number of RPC messages processed in each protocol stack loop. The value is a positive integer.| |nic_read_num|128|Number of data packets read from the NIC in each protocol stack cycle. The value is a positive integer.| |mbuf_pool_size|1024000|Size of the mbuf address pool applied for during initialization. Set this parameter based on the NIC configuration. The value must be a positive integer less than 5120000 and not too small, otherwise the startup fails.| +|stack_interrupt|0/1|Controls interrupt mode: **0** (default) disables it, **1** enables it.| +|stack_num|0-320|Configures automatic NUMA-bound stacks. **0** disables the feature. When active, it automatically calculates huge page memory using **tcp_conn_count** and **mbuf_count_per_conn** parameters. Overrides **num_cpus** when both are set. Defaults to **1** if neither is configured. Currently limited to XDP mode with single stack thread (**stack_num** <= 1).| lstack.conf example: @@ -317,6 +320,9 @@ Restrictions of Gazelle are as follows: - The active/standby mode (bond1 mode) of ltran supports active/standby switchover only when a fault occurs at the link layer (for example, the network cable is disconnected), but does not support active/standby switchover when a fault occurs at the physical layer (for example, the NIC is powered off or removed). - VM NICs do not support multiple queues. - KNI must be enabled with UDP unless the NIC driver (such as mlx5) supports user mode and kernel mode at the same time. +- Interrupt mode: Compatible only with ipvlan interfaces in containers using XDP mode for packet handling. Incompatible with shared thread mode, Hinic 1822 NICs, bonded NICs, and virtio NICs using igb_uio drivers. Note: Performance may decrease slightly due to more frequent wake-ups. +- XDP mode: Supports only ipvlan L2 mode interfaces with single-queue configuration on one interface. Requires kernel XDP support. Does not support single NIC functionality or non-userspace traffic forwarding. +- Automatic container resource deployment: Requires XDP mode. Multi-queue configurations not supported. ### Operation Restrictions diff --git a/docs/en/docs/Gazelle/public_sys-resources/icon-note.gif b/docs/en/docs/Gazelle/public_sys-resources/icon-note.gif new file mode 100644 index 0000000000000000000000000000000000000000..6314297e45c1de184204098efd4814d6dc8b1cda Binary files /dev/null and b/docs/en/docs/Gazelle/public_sys-resources/icon-note.gif differ diff --git a/docs/en/docs/SBOM/SBOM.md b/docs/en/docs/SBOM/SBOM.md new file mode 100644 index 0000000000000000000000000000000000000000..8b6b67fef3ab6afdad952b185c2ae5bba3adf38a --- /dev/null +++ b/docs/en/docs/SBOM/SBOM.md @@ -0,0 +1,50 @@ +# 1. Introduction to SBOM + +A Software Bill of Materials (SBOM) serves as a formal, machine-readable inventory that uniquely identifies software components and their contents. Beyond basic identification, it tracks copyright and licensing details. Organizations use SBOM to enhance supply chain transparency, and it is rapidly becoming a mandatory deliverable in software distribution. + +# 2. SBOM Core Requirements + +The National Telecommunications and Information Administration (NTIA) has established baseline requirements for SBOM implementation. These essential data elements enable component tracking throughout the software supply chain and serve as the foundation for extended features such as license tracking and vulnerability monitoring. + +| Core Field | Definition | +| ------------------------------- | ------------------------------------------------------------ | +| Supplier | Entity responsible for component creation and identification | +| Component | Official designation of the software unit | +| Version | Tracking identifier for component iterations | +| Other identifiers | Supplementary reference keys | +| Dependencies | Mapping of component relationships and inclusions | +| SBOM author | Entity generating the SBOM documentation | +| Timestamp | SBOM generation date and time | +| **Recommended Optional Fields** | | +| Component hash | Digital fingerprint for security verification | +| Lifecycle phase | Development stage at SBOM creation | + +# 3. openEuler SBOM Implementation + +openEuler's SBOM framework incorporates extensive metadata tracking through SPDX, including: + +| Base Field | SPDX Path | +| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Supplier | document->packages->supplier | +| Name | document->packages->name | +| Version | document->packages->versionInfo (epoch:version-release in openEuler) | +| Other identifiers | document->packages->externalRefs->purl | +| Dependencies | document->packages->externalRefs->purl | +| SBOM author | document->creationInfo->creators | +| Timestamp | document->creationInfo->created | +| Component hash | document->packages->checksums | +| Lifecycle phase | Not supported | +| Other relationships | Internal subcomponents: document->packages->externalRefs(category:PROVIDE_MANAGER)->purl
Runtime dependencies: document->relationships(relationshipType:DEPENDS_ON) | +| License info | document->packages->licenseDeclared document->packages->licenseConcluded | +| Copyright info | document->packages->copyrightText | +| Upstream community | document->packages->externalRefs(category:SOURCE_MANAGER)->url | +| Patch information | Patch files: document->files(fileTypes:SOURCE)
Patch relationships: document->relationships(relationshipType:PATCH_APPLIED) | +| Component source | document->packages->downloadLocation | +| Component details | document->packages->description document->packages->summary | +| Website/Blog | document->packages->homepage | + +# 4. SBOM Structure + +The system uses RPM packages as the fundamental unit for SBOM generation and analysis. + +![](../../../../image.png) diff --git a/docs/en/docs/Virtualization/Skylark.md b/docs/en/docs/Virtualization/Skylark.md index 1de2ad58f78138ddc61d83eca5fbc050569fc6fc..f910eb621764ba92108e1481f11739d55adb1518 100644 --- a/docs/en/docs/Virtualization/Skylark.md +++ b/docs/en/docs/Virtualization/Skylark.md @@ -1,12 +1,12 @@ # Skylark - [Skylark](#skylark) - - [Skylark Introduction](#skylark-introduction) - - [Architecture and Features](#architecture-and-features) - - [Skylark Installation](#skylark-installation) - - [Skylark Configuration](#skylark-configuration) - - [Skylark Usage](#skylark-usage) - - [Best Practices](#best-practices) + - [Skylark Introduction](#skylark-introduction) + - [Architecture and Features](#architecture-and-features) + - [Skylark Installation](#skylark-installation) + - [Skylark Configuration](#skylark-configuration) + - [Skylark Usage](#skylark-usage) + - [Best Practices](#best-practices) ## Skylark Introduction @@ -27,6 +27,7 @@ For details about how to better use the priority feature of Skylark in actual ap ### Overall Architecture The core class of Skylark is `QoSManager`. Class members include data collection class instances, QoS analysis class instances, QoS control class instances, and task scheduling class instances. + - `DataCollector`: data collection class. It has the `HostInfo` and `GuestInfo` members, which collect host information and VM information, respectively. - `PowerAnalyzer`: power consumption analysis class, which analyzes power consumption interference and low-priority VMs to be restricted. - `CpuController`: CPU bandwidth control class, which limits the CPU bandwidth of low-priority VMs. @@ -34,6 +35,7 @@ The core class of Skylark is `QoSManager`. Class members include data collection - `BackgroundScheduler`: task scheduling class, which periodically drives the preceding modules to continuously manage QoS. After checking the host environment, Skylark creates a daemon process. The daemon has a main scheduling thread and one or more job threads. + - The main scheduling thread is unique. It connects to libvirt, creates and initializes the `QosManager` class instance, and then starts to drive the Job threads. - Each Job thread periodically executes a QoS management task. @@ -69,6 +71,7 @@ During initialization, Skylark sets the **cpu.qos_level** field of the slice lev ### Hardware Requirements Processor architecture: AArch64 or x86_64 + - For Intel processors, the RDT function must be supported. - For the AArch64 architecture, only Kunpeng 920 processor is supported, and the BIOS must be upgraded to 1.79 or later to support the MPAM function. @@ -114,18 +117,18 @@ After the Skylark component is installed, you can modify the configuration file - **TDP_THRESHOLD** is a floating point number used to control the maximum power consumption of a VM. When the power consumption of the host exceeds **TDP * TDP_THRESHOLD**, a TDP hotspot occurs, and a power consumption control operation is triggered. The value ranges from 0.8 to 1, with the default value being 0.98. - **FREQ_THRESHOLD** is a floating point number used to control the minimum CPU frequency when a TDP hotspot occurs on the host. The value ranges from 0.8 to 1, with the default value being 0.98. - 1. When the frequency of some CPUs is lower than **max_freq * FREQ_THRESHOLD**, Skylark limits the CPU bandwidth of low-priority VMs running on these CPUs. - 2. If such a CPU does not exist, Skylark limits the CPU bandwidth of some low-priority VMs based on the CPU usage of low-priority VMs. + 1. When the frequency of some CPUs is lower than **max_freq * FREQ_THRESHOLD**, Skylark limits the CPU bandwidth of low-priority VMs running on these CPUs. + 2. If such a CPU does not exist, Skylark limits the CPU bandwidth of some low-priority VMs based on the CPU usage of low-priority VMs. - **QUOTA_THRESHOLD** is a floating point number used to control the CPU bandwidth that a restricted low-priority VM can obtain (CPU bandwidth before restriction x **QUOTA_THRESHOLD**). The value ranges from 0.8 to 1, with the default value being 0.9. - **ABNORMAL_THRESHOLD** is an integer used to control the number of low-priority VM restriction periods. The value ranges from 1 to 5, with the default value being 3. - 1. In each power consumption control period, if a low-priority VM is restricted, its number of remaining restriction periods is updated to **ABNORMAL_THRESHOLD**. Otherwise, its number of remaining restriction periods decreases by 1. - 2. When the number of remaining restriction periods of the VM is 0, the CPU bandwidth of the VM is restored to the value before the restriction. + 1. In each power consumption control period, if a low-priority VM is restricted, its number of remaining restriction periods is updated to **ABNORMAL_THRESHOLD**. Otherwise, its number of remaining restriction periods decreases by 1. + 2. When the number of remaining restriction periods of the VM is 0, the CPU bandwidth of the VM is restored to the value before the restriction. ### LLC/MB Interference Control -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. +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 Kunpeng 920 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. @@ -192,4 +195,4 @@ Skylark detects VM creation events, manages VMs of different priorities, and per To ensure optimal performance of high-priority VMs, you are advised to bind each vCPU of high-priority VMs to a physical CPU. To enable low-priority VMs to make full use of idle physical resources, you are advised to bind vCPUs of low-priority VMs to CPUs that are bound to high-priority VMs. -To ensure that low-priority VMs are scheduled when high-priority VMs occupy CPU resources for a long time, you are advised to reserve a small number of for low-priority VMs. \ No newline at end of file +To ensure that low-priority VMs are scheduled when high-priority VMs occupy CPU resources for a long time, you are advised to reserve a small number of for low-priority VMs. diff --git a/docs/en/docs/Virtualization/managing-devices.md b/docs/en/docs/Virtualization/managing-devices.md index 3cb24b2db805b5f27bd0210ae707e17a7b64499b..586e09621ab949b108c7be901450909b85a6dd3b 100644 --- a/docs/en/docs/Virtualization/managing-devices.md +++ b/docs/en/docs/Virtualization/managing-devices.md @@ -296,20 +296,21 @@ PCI passthrough directly assigns a physical PCI device on the host to a VM. The Single Root I/O Virtualization (SR-IOV) is a hardware-based virtualization solution. With the SR-IOV technology, a physical function (PF) can provide multiple virtual functions (VFs), and each VF can be directly assigned to a VM. This greatly improves hardware resource utilization and I/O performance of VMs. A typical application scenario is SR-IOV passthrough for NICs. With the SR-IOV technology, a physical NIC (PF) can function as multiple VF NICs, and then the VFs can be directly assigned to VMs. >![](./public_sys-resources/icon-note.gif) **NOTE:** -> ->- SR-IOV requires the support of physical hardware. Before using SR-IOV, ensure that the hardware device to be directly assigned supports SR-IOV and the device driver on the host OS works in SR-IOV mode. ->- The following describes how to query the NIC model: ->In the following command output, values in the first column indicate the PCI numbers of NICs, and **19e5:1822** indicates the vendor ID and device ID of the NIC. -> ->```shell ->$ lspci | grep Ether ->05:00.0 Ethernet controller: Device 19e5:1822 (rev 45) ->07:00.0 Ethernet controller: Device 19e5:1822 (rev 45) ->09:00.0 Ethernet controller: Device 19e5:1822 (rev 45) ->0b:00.0 Ethernet controller: Device 19e5:1822 (rev 45) ->81:00.0 Ethernet controller: Intel Corporation 82599ES 10-Gigabit SFI/SFP+ Network Connection (rev 01) ->81:00.1 Ethernet controller: Intel Corporation 82599ES 10-Gigabit SFI/SFP+ Network Connection (rev 01) ->``` + +- SR-IOV requires the support of physical hardware. Before using SR-IOV, ensure that the hardware device to be directly assigned supports SR-IOV and the device driver on the host OS works in SR-IOV mode. +- The following describes how to query the NIC model: + + In the following command output, values in the first column indicate the PCI numbers of NICs, and **19e5:1822** indicates the vendor ID and device ID of the NIC. + +```shell +$ lspci | grep Ether +05:00.0 Ethernet controller: Device 19e5:1822 (rev 45) +07:00.0 Ethernet controller: Device 19e5:1822 (rev 45) +09:00.0 Ethernet controller: Device 19e5:1822 (rev 45) +0b:00.0 Ethernet controller: Device 19e5:1822 (rev 45) +81:00.0 Ethernet controller: Intel Corporation 82599ES 10-Gigabit SFI/SFP+ Network Connection (rev 01) +81:00.1 Ethernet controller: Intel Corporation 82599ES 10-Gigabit SFI/SFP+ Network Connection (rev 01) +``` #### Procedure @@ -456,14 +457,14 @@ To configure SR-IOV passthrough for a NIC, perform the following steps: >Disabling the SR-IOV function: >To disable the SR-IOV function after the VM is stopped and no VF is in use, run the following command: >The following uses the Hi1822 NIC (corresponding network interface name: eth0) as an example: -> + > >```shell >echo 0 > /sys/class/net/eth0/device/sriov_numvfs >``` #### SR-IOV Passthrough for the HPRE Accelerator -The accelerator engine is a hardware acceleration solution provided by TaiShan 200 server based on the Kunpeng 920 processor. The HPRE accelerator is used to accelerate SSL/TLS applications. It significantly reduces processor consumption and improves processor efficiency. +The accelerator engine is a hardware acceleration solution provided by TaiShan 200 servers. The HPRE accelerator is used to accelerate SSL/TLS applications. It significantly reduces processor consumption and improves processor efficiency. On the Kunpeng server, the VF of the HPRE accelerator on the host needs to be passed through to the VM for internal services of the VM. **Table 3** HPRE accelerator description @@ -816,11 +817,11 @@ The cloud that may be disconnected from the storage plane is used as the backend - After a storage fault occurs, the following problems cannot be solved even though disk I/O suspension exists: - 1. Failed to execute advanced storage features. + 1. Failed to execute advanced storage features. - Advanced features include virtual disk hot swapping, virtual disk creation, VM startup, VM shutdown, forcible VM shutdown, VM hibernation and wakeup, VM storage hot migration, VM storage hot migration cancellation, VM storage snapshot creation, VM storage snapshot combination, and VM disk capacity query, VM online scale-out, virtual CD-ROM drive insertion and ejection. + Advanced features include virtual disk hot swapping, virtual disk creation, VM startup, VM shutdown, forcible VM shutdown, VM hibernation and wakeup, VM storage hot migration, VM storage hot migration cancellation, VM storage snapshot creation, VM storage snapshot combination, and VM disk capacity query, VM online scale-out, virtual CD-ROM drive insertion and ejection. - 2. Failed to execute the VM life cycle. + 2. Failed to execute the VM life cycle. - When a VM configured with disk I/O suspension initiates hot migration, the XML configuration of the destination disk must contain the same disk I/O suspension configuration as that of the source disk. diff --git a/docs/en/docs/desktop/DDE-user-guide.md b/docs/en/docs/desktop/DDE-user-guide.md old mode 100755 new mode 100644 index 3499b4ea959027d35fc5b306418f353acc81dd4c..66bdefb1c11ceec9f99e71132ebb51b7f5e575f4 --- a/docs/en/docs/desktop/DDE-user-guide.md +++ b/docs/en/docs/desktop/DDE-user-guide.md @@ -1,8 +1,7 @@ - - # DDE Desktop Environment ## Overview + DDE desktop environment is an elegant, secure, reliable and easy to use GUI comprised of the desktop, dock, launcher and control center. Acting as the key basis for our operating system, its main interface is shown as below. ![1|desk](./figures/43.jpg) @@ -13,8 +12,6 @@ When you enter DDE for the very first time, a welcome program will automatically ![0|welcome](./figures/46.png) - - ## Desktop Desktop is the main screen you see after logging in. On the desktop, you can create a new file/folder, sort files, open in terminal, set wallpaper and screensaver and etc. You can also add shortcuts for applications on desktop by using [Send to desktop](#set-app-shortcut). @@ -22,6 +19,7 @@ Desktop is the main screen you see after logging in. On the desktop, you can cre ![0|contextmenu](./figures/41.png) ### Create New Folder/Document + Just as in File Manager, you can create a new folder/document on the desktop, or do some operations for the files on it. - Right-click the desktop, select **New folder** and enter the name for it. @@ -48,17 +46,13 @@ Sort the files on your desktop to make it organized and fit your needs. 1. Right-click the desktop. 2. Click **Sort by**, you can: - - Click **Name** to display files in the name sequence. - - Click **Size** to display files in the size sequence. - - Click **Type** to display files in type. - - Click **Time modified** to display files in the order of last modified date. - +- Click **Name** to display files in the name sequence. +- Click **Size** to display files in the size sequence. +- Click **Type** to display files in type. +- Click **Time modified** to display files in the order of last modified date. > ![tips](./figures/icon125-o.svg)Tips: *Check **Auto arrange**, icons on the desktop will be listed in order automatically, and if an icon is removed, another one will fill in the blank.* - - - ### Adjust Icon Size 1. Right-click the desktop. @@ -67,6 +61,7 @@ Sort the files on your desktop to make it organized and fit your needs. > ![tips](./figures/icon125-o.svg)Tips: *Press **Ctrl** + ![=](./figures/icon134-o.svg)/![-](./figures/icon132-o.svg) scrolling mouse wheel to adjust icon size on the desktop and in Launcher.* ### Set Display + You can set display scaling, screen resolution, brightness and so on from the desktop. 1. Right-click the desktop. @@ -75,6 +70,7 @@ You can set display scaling, screen resolution, brightness and so on from the de > ![notes](./figures/icon99-o.svg)Notes: *For specific operations, please refer to [Display](#Display).* ### Change Wallpaper + Select some elegant and fashionable wallpapers to beautify your desktop and make it distinctive. 1. Right-click the desktop. @@ -84,8 +80,6 @@ Select some elegant and fashionable wallpapers to beautify your desktop and make ![1|wallpaper](./figures/63.jpg) - - > ![tips](./figures/icon125-o.svg)Tips: *You can also set your favorite picture as wallpaper in an image viewer.* ### Clipboard @@ -96,7 +90,7 @@ All the texts, pictures and documents cut and copied by the current user after l 2. Double-click in the clipboard to copy the current content quickly and the corresponding block will be moved to the top of the clipboard. -3. Select the target destination to paste it. +3. Select the target destination to paste it. 4. Click![close](./figures/icon57-o.svg)to delete the current content and click **Clear All** to clear the clipboard. @@ -107,9 +101,8 @@ All the texts, pictures and documents cut and copied by the current user after l Dock is at the bottom of the desktop by default to help you quickly open frequently-used applications, which includes Launcher, applications, system tray, and plugins. In the dock, you can open launcher, show the desktop, enter the workspaces, open and exit apps, set input methods, adjust the volume, connect to the network, view the calendar and enter the shutdown interface, and so on. ### Icons on Dock -In the Dock, there are icons of Launcher, applications, system tray, and plugins. - +In the Dock, there are icons of Launcher, applications, system tray, and plugins. ![1|fashion](./figures/45.png) @@ -128,6 +121,7 @@ In the Dock, there are icons of Launcher, applications, system tray, and plugins > ![tips](./figures/icon125-o.svg)Tips: *In Efficient Mode, you can click the right side of Dock to show the desktop. Move the cursor to the running app in the Dock and you will see its preview window.* ### Switch Display Mode + There are two display modes of Dock: fashion mode and efficient mode, icon sizes are different in them. ![1|fashion](./figures/46.png) @@ -140,14 +134,15 @@ You can switch the display modes by the following operations: 2. Select the display mode. ### Change Dock Location + You can place Dock on any direction of your desktop. 1. Right-click the Dock and select **Location**. 2. Select a location. ### Change Dock Height -Drag the top edge to increase or decrease the height. +Drag the top edge to increase or decrease the height. ### Show/Hide Plugins @@ -155,9 +150,8 @@ Drag the top edge to increase or decrease the height. 2. On the submenu, you can check or uncheck **Trash, Power, Show Desktop, Onboard**, and **Datetime** to show or hide the corresponding icon in the Dock. ### View Notifications -When there are system or application notifications, they will be shown in the middle of the screen. If there are buttons in the message, click buttons to do the actions; if there are not, click the message to close it. - +When there are system or application notifications, they will be shown in the middle of the screen. If there are buttons in the message, click buttons to do the actions; if there are not, click the message to close it. ![notification](./figures/51.png) @@ -187,6 +181,7 @@ There are two ways to enter the shutdown interface: > ![notes](./figures/icon99-o.svg)Notes: ![userswitch_normal](./figures/icon128-o.svg) *will be shown if there are multiple accounts in the system.* ### Trash + You can find all deleted files in the trash, which can be restored or emptied. #### Restore Files @@ -200,14 +195,15 @@ You can restore deleted files in Trash or press **Ctrl** + **Z** to restore the > ![attention](./figures/icon52-o.svg)Attention: *If the original folder of the file has been deleted, the deleted file will be restored to a new folder automatically created.* #### Empty Trash + In the trash, click **Empty** to permanently delete all the files in the trash. ## Launcher + Launcher ![launcher](./figures/icon66-o.svg) helps you manage all the installed applications, where you can quickly find an application by category navigation or by a search. > ![tips](./figures/icon125-o.svg)Tips: *You can view newly installed applications in Launcher. The newly-installed ones are followed with a blue dot.* - ### Switch Launcher Modes There are two display modes of Launcher: fullscreen mode and mini mode. Click the icon at the upper right corner to switch modes. @@ -237,21 +233,24 @@ In Launcher, you can scroll up and down to find an application, or locate it wit If you already know the application name, just search for it. ### Set App Shortcut + The shortcut offers a method to run applications easily and quickly. #### Create App Shortcut + Send the application icon to the desktop or Dock to facilitate the follow-up operations. In Launcher, right-click an app icon and you can: -* Select **Send to desktop** to create a shortcut on the desktop. -* Select **Send to dock** to fix the application icon in Dock. +- Select **Send to desktop** to create a shortcut on the desktop. +- Select **Send to dock** to fix the application icon in Dock. ![0|sendto](./figures/58.png) > ![notes](./figures/icon99-o.svg)Notes: *You can drag the application icon from Launcher to Dock. But you cannot drag and drop the application while it is running. Then you can right-click the application icon in Dock and select **Dock** to fix it in order to open it quickly for the next time.* #### Delete Shortcut + Delete a shortcut from the desktop directly, or remove it from Dock or Launcher. **Remove the shortcut from Dock:** @@ -262,12 +261,14 @@ Delete a shortcut from the desktop directly, or remove it from Dock or Launcher. **Remove the shortcut from Launcher:** In Launcher, right-click the icon and you can: + - Select **Remove from desktop** to delete the shortcut from the desktop. - Select **Remove from dock** to remove the application icon from Dock. > ![notes](./figures/icon99-o.svg)Notes: *The above operations only delete the shortcut rather than uninstall the applications.* ### Run Applications + For the applications whose shortcuts have been created on the desktop or Dock, you can open them in the following ways: - Double-click the desktop icon or right-click it and select **Open**. @@ -277,11 +278,12 @@ To open the application only shown in Launcher, click the icon or right-click it > ![tips](./figures/icon125-o.svg)Tips: *For the frequently-used applications, right-click the app icon and select **Add to startup** to run it when the computer boots.* - ## Control Center + You can manage the system settings in Control Center, including account management, network settings, date and time, personalization, display settings, etc. After entering the desktop environment, click ![controlcenter](./figures/icon58-o.svg) to open Control Center. ### Homepage Introduction + The homepage of Control Center provides several setting modules and click one to enter the detailed settings. ![0|dcchomepage](./figures/42.png) @@ -299,6 +301,7 @@ The title bar contains the back button, search box, main menu and the window but - Main menu: Click ![menu](./figures/icon83-o.svg) to enter the main menu where you can set the window theme, view the manual and exit. ### Accounts + You have already created an account when installing the system. Here you can modify account settings or create a new one. ![0|account](./figures/38.png) @@ -311,7 +314,6 @@ You have already created an account when installing the system. Here you can mod 4. Click **Create**. 5. Input the password of the current user account in the authentication dialog box, and the new account will be added to the account list. - #### Change Account Avatar 1. On the homepage of Control Center, click ![account_normal](./figures/icon49-o.svg). @@ -320,6 +322,7 @@ You have already created an account when installing the system. Here you can mod 4. Select a avatar or upload a local avatar. #### Set Full Name + The account full name is shown in account list and system login interface and you can set it as needed. 1. On the homepage of Control Center, click ![account_normal](./figures/icon49-o.svg). @@ -358,11 +361,11 @@ When you add or modify accounts, you can: - Select the group with the same name as another user when the account was previously added. ### Display + Set screen resolution, brightness, direction and display scaling properly to have the best visual effect. ![0|display](./figures/44.png) - #### Single Screen Settings ##### Change Resolution @@ -376,11 +379,12 @@ Set screen resolution, brightness, direction and display scaling properly to hav 1. On the homepage of Control Center, click ![display_normal](./figures/icon72-o.svg). 2. Click **Brightness**. - - Drag the slider to set screen brightness. - - Switch on **Night Shift**, the screen hue will be auto-adjusted according to your location. - - Switch on **Auto Brightness**, the monitor will change the brightness automatically according to ambient light (shown only if PC has a light sensor). + - Drag the slider to set screen brightness. + - Switch on **Night Shift**, the screen hue will be auto-adjusted according to your location. + - Switch on **Auto Brightness**, the monitor will change the brightness automatically according to ambient light (shown only if PC has a light sensor). ##### Change Refresh Rate + 1. On the homepage of Control Center, click ![display_normal](./figures/icon72-o.svg). 2. Click **Refresh Rate**. 3. Select a proper one, and click **Save**. @@ -399,9 +403,9 @@ Expand your desktop by multiple screens! Use VGA/HDMI/DP cable to connect your c 1. On the homepage of Control Center, click ![display_normal](./figures/icon72-o.svg). 2. Click **Multiple Displays**. 3. Select a display mode: - - **Duplicate**: display the same image on other screens. - - **Extend**: expand the desktop across the screens. - - **Customize**: customize the display settings for multiple screens. + - **Duplicate**: display the same image on other screens. + - **Extend**: expand the desktop across the screens. + - **Customize**: customize the display settings for multiple screens. In multiple displays, press **Super** + **P** to show its OSD. @@ -410,7 +414,7 @@ Operations are as follows: 1. Hold **Super** and press **P** or click to select the options. 2. Release the keys, the selected mode will take into effect. ->![notes](./figures/icon99-o.svg)Notes: *When the multiple displays are in the extend mode, only the main screen supports desktop icon display, right-click menu operation and other functions, while the sub-screens do not.* +> ![notes](./figures/icon99-o.svg)Notes: *When the multiple displays are in the extend mode, only the main screen supports desktop icon display, right-click menu operation and other functions, while the sub-screens do not.* ##### Custom Settings @@ -423,6 +427,7 @@ Operations are as follows: > ![notes](./figures/icon99-o.svg)Notes: *"Merge" means duplicate mode, "Split" means extend mode.* ### Default Application Settings + If you have installed several applications with similar functions, such as text editor, choose one of them to be the default application to open that type of file. ![0|default](./figures/39.png) @@ -456,13 +461,14 @@ To delete the default applications you have added, do as below: 2. Select a file type. 3. Click ![close](./figures/icon57-o.svg) after the application name to delete it. - ### Personalization Settings + You can set theme, accent color, font, change the appearance of the desktop and windows to your favorite style. ![0|personalise](./figures/56.png) #### Set Window Theme + 1. On the homepage of Control Center, click ![personalization_normal](./figures/icon105-o.svg). 2. Click **General**. 3. Select one window theme, which will be used as system theme. @@ -470,6 +476,7 @@ You can set theme, accent color, font, change the appearance of the desktop and > ![notes](./figures/icon99-o.svg)Notes: *"Auto" means changing window theme automatically according to the sunset and sunrise time. After sunrise, it is light theme; after sunset, it is dark theme.* #### Change Accent Color + Accent color refers to the color used when you select one option or file in the system. 1. On the homepage of Control Center, click ![personalization_normal](./figures/icon105-o.svg). @@ -481,7 +488,6 @@ Accent color refers to the color used when you select one option or file in the 1. On the homepage of Control Center, click ![personalization_normal](./figures/icon105-o.svg). 2. Click **Icon Theme** and select an icon style. - #### Set Cursor Theme 1. On the homepage of Control Center, click ![personalization_normal](./figures/icon105-o.svg). @@ -493,8 +499,8 @@ Accent color refers to the color used when you select one option or file in the 2. Click **Font**. 3. Set the font and font size for the system. - ### Network Settings + After login, you need to connect to a network first and then surf the Internet! > ![tips](./figures/icon125-o.svg)Tips: *Check your network status by hovering over or clicking the network icon in Dock.* @@ -515,6 +521,7 @@ Wired network is secure and stable, which makes it the most common way to connec You can also edit and add a new wired network in the setting page. #### Mobile Network + If you are at a place without network, mobile network adapter is a useful tool to help you connect to the Internet as long as the place is covered by telephone signals. 1. Plug the mobile network adapter into your computer USB port. @@ -534,7 +541,6 @@ DSL is a dial-up connection using a standard phone line and analog modem to acce 4. Enter the name, your account and password the operator provides. 5. Click **Save**. The connection will automatically start. - #### VPN VPN is a virtual private network. Its main function is to establish a private network on the public network for encrypted communication. Whether you are on a business trip or working at home, you can use VPN to access intranet resources as long as you can access the Internet. You can also use VPN to speed up access to websites in other countries. @@ -551,9 +557,10 @@ VPN is a virtual private network. Its main function is to establish a private ne 1. On the homepage of Control Center, click ![network_normal](./figures/icon97-o.svg). 2. Click **System Proxy**. - - Click **None** and **Save** to disable the proxy. - - Click **Manual** and input the address and port of proxy servers. - - Click **Auto** and input a URL to configure the proxy info. + +- Click **None** and **Save** to disable the proxy. +- Click **Manual** and input the address and port of proxy servers. +- Click **Auto** and input a URL to configure the proxy info. #### Application Proxy @@ -584,25 +591,21 @@ Set your speaker and microphone properly to make you hear more comfortable and m 2. Click **Output** to: - - Select output device type from the dropdown list after **Output Device**. - - - Drag the slider to adjust output volume and left/right balance. - - Switch on **Volume Boost**, the volume could be adjustable from 0~150% (the former range is 0~100%). - + - Select output device type from the dropdown list after **Output Device**. + - Drag the slider to adjust output volume and left/right balance. + - Switch on **Volume Boost**, the volume could be adjustable from 0~150% (the former range is 0~100%). #### Input 1. On the homepage of Control Center, click ![sound_normal](./figures/icon116-o.svg). 2. Click **Input** to: - - Select input device type from the dropdown list after **Input Device**. - - Adjust input volume by dragging the slider. - - You can enable **Automatic Noise Suppression** by clicking the button after "Automatic Noise Suppression". + - Select input device type from the dropdown list after **Input Device**. + - Adjust input volume by dragging the slider. + - You can enable **Automatic Noise Suppression** by clicking the button after "Automatic Noise Suppression". > ![tips](./figures/icon125-o.svg)Tips: *Usually, you need to turn up the input volume to make sure that you can hear the sound of the sound source, but the volume should not be too high, because it will cause distortion of the sound. Here is how to set input volume: Speak to your microphone at a normal volume and view "Input Level". If the indicator changes obviously according to the volume, then the input volume is at a proper level.* - - #### System Sound Effects 1. On the homepage of Control Center, click ![sound_normal](./figures/icon116-o.svg). @@ -611,11 +614,13 @@ Set your speaker and microphone properly to make you hear more comfortable and m > ![tips](./figures/icon125-o.svg)Tips: *Click to listen to the sound effect.* ### Date and Time + Set your timezone properly to have correct date and time. You can also change them manually. ![0|time](./figures/62.png) #### Change Timezone + You have selected the timezone during system installation and do as follows to change it. 1. On the homepage of Control Center, click ![time](./figures/icon124-o.svg). @@ -624,6 +629,7 @@ You have selected the timezone during system installation and do as follows to c 4. Click **Confirm**. #### Add Timezone + Add another timezone to see the date and time there. 1. On the homepage of Control Center, click ![time](./figures/icon124-o.svg). @@ -639,12 +645,13 @@ Add another timezone to see the date and time there. 4. Click ![delete](./figures/icon71-o.svg) to remove the timezone. #### Change Date and Time + Note that the auto-sync function will be disabled after changing date and time manually. 1. On the homepage of Control Center, click ![time](./figures/icon124-o.svg). 2. Click **Time Settings**. - - Switch on/off **Auto Sync**. - - Enter the correct date and time. + - Switch on/off **Auto Sync**. + - Enter the correct date and time. 3. Click **Confirm**. #### Set Time Format @@ -654,23 +661,20 @@ Setting the format of time and date is supported. 1. On the homepage of Control Center, click ![time](./figures/icon124-o.svg). 2. Click **Time Format** to set the first day of week, long date, short date, long time, and short time. - - ### Power Management Power management helps you to improve system safety. ![0|power](./figures/57.png) - - -#### Time to Suspend +#### Time to Suspend 1. On the homepage of Control Center, click ![power_normal](./figures/icon107-o.svg). 2. Click **Plugged In**. 3. Set the time to suspend. #### Time to Lock Screen + 1. On the homepage of Control Center, click ![power_normal](./figures/icon107-o.svg). 2. Click **Plugged In**. 3. Set the time to lock screen. @@ -683,8 +687,6 @@ Power management helps you to improve system safety. Any operation done here will take effect immediately. At the same time, the system will notify the user that the power button setting is changed. - - ### Mouse Mouse is common computer input device. Using the mouse, you can make the operation easier and faster. @@ -700,6 +702,7 @@ Mouse is common computer input device. Using the mouse, you can make the operati > ![notes](./figures/icon99-o.svg)Notes: *If "Left Hand" is enabled, left-click and right-click of the mouse exchange.* #### Mouse + After inserting or connecting the mouse, make relevant settings in the Control Center to make it more in line with your usage habits. 1. On the homepage of Control Center, click ![mouse_touchpad_normal](./figures/icon94-o.svg). @@ -708,10 +711,12 @@ After inserting or connecting the mouse, make relevant settings in the Control C 4. Switch on **Natural Scrolling**/**Mouse Acceleration** if you want. > ![notes](./figures/icon99-o.svg)Notes: -> - *Turn on the mouse acceleration to improve the accuracy of the pointer. The moving distance of the mouse pointer on the screen will increase according to the acceleration of the moving speed. It can be turned on or off according to the usage.* -> - *If Natural Scrolling is enabled, when you scroll down, the page will scroll down, when you scroll up, the page will scroll up as well.* +> +> - *Turn on the mouse acceleration to improve the accuracy of the pointer. The moving distance of the mouse pointer on the screen will increase according to the acceleration of the moving speed. It can be turned on or off according to the usage.* +> - *If Natural Scrolling is enabled, when you scroll down, the page will scroll down, when you scroll up, the page will scroll up as well.* ### Keyboard and Language + Set keyboard properties and select your keyboard layout to keep your typing habit. You can also adjust the keyboard layout according to the country and language, change system language, and customize shortcuts here. ![0|keyboard](./figures/59.png) @@ -725,6 +730,7 @@ Set keyboard properties and select your keyboard layout to keep your typing habi 5. Switch on **Numeric Keypad** and **Caps Lock Prompt** if you want. #### Keyboard Layout + Set the keyboard layout to customize the keyboard for the current language. When you press a key on the keyboard, the keyboard layout controls which characters are displayed on the screen. After changing the keyboard layout, the characters on the screen may not match the characters on the keyboard keys. You have set a keyboard layout during system installation, but you can add more for other purposes. @@ -758,6 +764,7 @@ You have set a keyboard layout during system installation, but you can add more The system language is the language you selected when you installed the system by default, which can be changed at any time. ##### Add System Language + Add multiple languages into the list to change language conveniently. 1. On the homepage of Control Center, click ![keyboard_normal](./figures/icon86-o.svg). @@ -775,6 +782,7 @@ Add multiple languages into the list to change language conveniently. > ![attention](./figures/icon52-o.svg)Attention: *The keyboard layout may also be changed in the process of switching the system language. Please make sure that you select a correct keyboard layout to enter the login password.* #### Shortcuts + The shortcut list includes all shortcuts in the system. View, modify and customize the shortcuts here as you want. ![0|shortcut](./figures/59.png) @@ -785,7 +793,6 @@ The shortcut list includes all shortcuts in the system. View, modify and customi 2. Click **Shortcuts**. 3. You can search or view the default shortcuts for system, window and workspace. - ##### Modify Shortcuts 1. On the homepage of Control Center, click ![keyboard_normal](./figures/icon86-o.svg). @@ -805,7 +812,7 @@ The shortcut list includes all shortcuts in the system. View, modify and customi 6. After being successfully added, click **Edit**. 7. Click ![delete](./figures/icon71-o.svg) to delete the custom shortcut. -> ![tips](./figures/icon125-o.svg)Tips: *To change the shortcut, click it and press a new shortcut to change it directly. To edit the name and command of the custom shortcut, click **Edit ** > ![edit](./figures/icon75-o.svg) near the shortcut name to enter the shortcut settings.* +> ![tips](./figures/icon125-o.svg)Tips: *To change the shortcut, click it and press a new shortcut to change it directly. To edit the name and command of the custom shortcut, click **Edit** > ![edit](./figures/icon75-o.svg) near the shortcut name to enter the shortcut settings.* ### System Info @@ -840,4 +847,3 @@ You can use the keyboard to switch between various interface areas, select objec | **Enter** | Execute the selected operation. | | **Space** | Preview the selected object in File Manager; start and pause the playback in Music and Movie; expand the drop-down options in the drop-down list (The enter key is also available.). | | **Ctrl** + **M** | Open the right-click menu. | - diff --git a/docs/en/docs/desktop/UKUI-user-guide.md b/docs/en/docs/desktop/UKUI-user-guide.md old mode 100755 new mode 100644 index c95f0ee9b71ca69661d6dddfe9075ad9f1ff0199..7389fa3213e9522143a642cb8ee310a9be32d408 --- a/docs/en/docs/desktop/UKUI-user-guide.md +++ b/docs/en/docs/desktop/UKUI-user-guide.md @@ -206,10 +206,10 @@ Click the icon "![](./figures/icon43-o.png)" to open the volume window, and ther ![Fig. 27 Mini Mode](./figures/27.png) -- According to Equipment - It contains input equipments and output equipments. +- According to devices + It contains input devices and output devices. - ![Fig. 28 According to Equipment List](./figures/28.png) + ![Fig. 28 According to device List](./figures/28.png) - According to Application It contains system volume and other applications' volume. @@ -259,7 +259,7 @@ There are three ways to switch windows: - Click the different window at the desktop. -- Use shortcut keys < Alt > + < Tab >. +- Use shortcut keys **Alt** + **Tab**. ## Start Menu @@ -277,9 +277,9 @@ When the mouse is over the right side of the start menu, it will appear a pre-ex - All Software: List all software, recently used software will be displayed on the top of this page. -- Alphabetical Category: List all softwares by first letter. +- Alphabetical Category: List all software by first letter. -- Functional category: List all softwares by their functions. +- Functional category: List all software by function. Users can click the button at top right corner to view full-screen menu mode. diff --git a/docs/en/docs/sysSentry/CPU-fault-inspection-plugin.md b/docs/en/docs/sysSentry/CPU-fault-inspection-plugin.md new file mode 100644 index 0000000000000000000000000000000000000000..3fca4c6286531f93b4aa37a5ca247c1f99dba191 --- /dev/null +++ b/docs/en/docs/sysSentry/CPU-fault-inspection-plugin.md @@ -0,0 +1,111 @@ +# CPU Fault Inspection Plugin + +## Hardware Requirements + +- AArch64 architecture + +## Plugin Installation + +### Prerequisites + +sysSentry must be installed by referring to [sysSentry Installation](./installation-and-usage.md). + +### Installing the Package + +```sh +yum install cpu_sentry ipmitool libxalarm -y +``` + +### Loading Kernel Modules + +```sh +modprobe cpu_inspect +modprobe inspector-atf +``` + +## Configuring CPU fault Inspection + +CPU fault inspection configurations are stored in **/etc/sysSentry/plugins/cpu_sentry.ini**. + +- Configuration items + +| Item | Default Value | Range | Description | +| ------------- | ------------- | ---------------------- | ---------------------------------------------- | +| cpu_list | default | List of CPU core IDs | CPUs to inspect | +| patrol_second | 60 | Positive integer | Inspection timeout in seconds | +| cpu_utility | 100 | Integers from 1 to 100 | Maximum CPU utilization allowed for inspection | + +- Configuration example + +```ini +[args] +cpu_list = default +patrol_second = 60 +cpu_utility = 100 +``` + +## Task Management + +### Loading Tasks + +Run `sentryctl reload cpu_sentry` to load CPU inspection tasks. +![](figures/load_cpu_sentry.png) + +### Managing Inspection + +- Start: `sentryctl start cpu_sentry` +- Monitor: `sentryctl status cpu_sentry` +- Stop: `sentryctl stop cpu_sentry` + +### Viewing Results + +Use `sentryctl get_result cpu_sentry`. The **details** section contains: + +```json +{ + ... ... + "details": { + "code":0, + "msg":"xxx", + "isolated_cpulist":"xxx" + } +} +``` + +details field definitions + +| Field | Description | +|-------|-------------| +| code | Error code:
0: No CPU issues found
1001: CPU 0 has issues, isolation not possible
1002: Some CPUs have issues, successfully isolated
1003: Invalid configuration
1004: Inspection execution error
1005: Inspection process killed | +| msg | Error description | +| isolated_cpulist | List of isolated CPUs (e.g., "10-13,15-18") | + +Example result with invalid **patrol_second** value (-1): +![](figures/result-invalid-params.png) + +### Viewing Inspection Logs + +Logs are stored in **/var/log/sysSentry/cpu_sentry.log**. Example log entry for invalid configuration: + +```sh +[root@localhost ~]# cat /var/log/sysSentry/cpu_sentry.log +ERROR:root:config 'cpu_list' (value [1--3]) is invalid in cpu_sentry.ini ! +[root@localhost ~]# +``` + +## Q&A + +- Why does `sentryctl start cpu_sentry` return success (exit code 0) even with invalid parameters? + + The `sentryctl` command and inspection tasks operate independently. A successful exit code (0) only indicates that the task was submitted successfully, not that it executed successfully. The inspection process validates parameters before execution and exits if they're invalid. To see the actual inspection results, use `sentryctl get_result cpu_sentry`. + ![Result Example](figures/return-code-invalid-params.png) + +- What causes the "Operation not supported" error when the inspector-atf module is loaded? + + This error indicates lack of BIOS support for CPU fault inspection. Check **dmesg** logs for confirmation. + +![BIOS Support Message](figures/bios-not-support-cpu-inspec.PNG) + +- Why is there more than a 1-second gap between **start_time** and **end_time**? + + CPU inspection enforces single-task execution. Before starting a new task, the system runs `pgrep` to check for existing inspection processes. This verification process varies in duration across different environments, accounting for the time difference. diff --git a/docs/en/docs/sysSentry/figures/acls-example.png b/docs/en/docs/sysSentry/figures/acls-example.png new file mode 100644 index 0000000000000000000000000000000000000000..d51c21d3cc2f1bd2104f392fec204f3c96fc4117 Binary files /dev/null and b/docs/en/docs/sysSentry/figures/acls-example.png differ diff --git a/docs/en/docs/sysSentry/figures/bios-not-support-cpu-inspec.PNG b/docs/en/docs/sysSentry/figures/bios-not-support-cpu-inspec.PNG new file mode 100644 index 0000000000000000000000000000000000000000..1339f28b7d61627d1dbc9ba31a88349f321240ca Binary files /dev/null and b/docs/en/docs/sysSentry/figures/bios-not-support-cpu-inspec.PNG differ diff --git a/docs/en/docs/sysSentry/figures/hbm-start-log.png b/docs/en/docs/sysSentry/figures/hbm-start-log.png new file mode 100644 index 0000000000000000000000000000000000000000..338af511801088a3cb714853f32114e81f7173f8 Binary files /dev/null and b/docs/en/docs/sysSentry/figures/hbm-start-log.png differ diff --git a/docs/en/docs/sysSentry/figures/load_cpu_sentry.png b/docs/en/docs/sysSentry/figures/load_cpu_sentry.png new file mode 100644 index 0000000000000000000000000000000000000000..ee97251ddffa3246300178917868c9dfc4760fdd Binary files /dev/null and b/docs/en/docs/sysSentry/figures/load_cpu_sentry.png differ diff --git a/docs/en/docs/sysSentry/figures/result-invalid-params.png b/docs/en/docs/sysSentry/figures/result-invalid-params.png new file mode 100644 index 0000000000000000000000000000000000000000..0380682e68a73e56d629df3cd41837c14a5f20a2 Binary files /dev/null and b/docs/en/docs/sysSentry/figures/result-invalid-params.png differ diff --git a/docs/en/docs/sysSentry/figures/return-code-invalid-params.png b/docs/en/docs/sysSentry/figures/return-code-invalid-params.png new file mode 100644 index 0000000000000000000000000000000000000000..bc02c9b14105f97188f9b56e54f6509ae77b2ef9 Binary files /dev/null and b/docs/en/docs/sysSentry/figures/return-code-invalid-params.png differ diff --git a/docs/en/docs/sysSentry/figures/sentryctl_list.png b/docs/en/docs/sysSentry/figures/sentryctl_list.png new file mode 100644 index 0000000000000000000000000000000000000000..beae34e7aad27225de755638a58e14ee84f6d5fa Binary files /dev/null and b/docs/en/docs/sysSentry/figures/sentryctl_list.png differ diff --git a/docs/en/docs/sysSentry/figures/sysSentry.png b/docs/en/docs/sysSentry/figures/sysSentry.png new file mode 100644 index 0000000000000000000000000000000000000000..950993debb782a051b013fd72d341bdc480828ab Binary files /dev/null and b/docs/en/docs/sysSentry/figures/sysSentry.png differ diff --git a/docs/en/docs/sysSentry/installation-and-usage.md b/docs/en/docs/sysSentry/installation-and-usage.md new file mode 100644 index 0000000000000000000000000000000000000000..05cd001ddde67f969da2cf29349a61da7ff5acd7 --- /dev/null +++ b/docs/en/docs/sysSentry/installation-and-usage.md @@ -0,0 +1,150 @@ +# sysSentry Installation + +## System Requirements + +openEuler 22.03 LTS SP4 + +## Prerequisites + +- A working openEuler 22.03 LTS SP4 installation (see [Installation Guide](../Installation/Installation.md)) +- Root access + +## Repository Setup + +Create a repository configuration file in **/etc/yum.repos.d/** (example: **/etc/yum.repos.d/openEuler.repo**). + +**AArch64:** + +```ini +[openEuler-22.03-LTS-SP4] +name=openEuler-22.03-LTS-SP4 +baseurl=http://repo.openeuler.org/openEuler-22.03-LTS-SP4/everything/aarch64/ +enabled=1 +gpgcheck=1 +gpgkey=http://repo.openeuler.org/openEuler-22.03-LTS-SP4/everything/aarch64/RPM-GPG-KEY-openEuler + +[openEuler-22.03-LTS-SP4-update] +name=openEuler-22.03-LTS-SP4-update +baseurl=http://repo.openeuler.org/openEuler-22.03-LTS-SP4/update/aarch64/ +enabled=1 +gpgcheck=0 +``` + +**x86_64** + +```ini +[openEuler-22.03-LTS-SP4] +name=openEuler-22.03-LTS-SP4 +baseurl=http://repo.openeuler.org/openEuler-22.03-LTS-SP4/everything/x86_64/ +enabled=1 +gpgcheck=1 +gpgkey=http://repo.openeuler.org/openEuler-22.03-LTS-SP4/everything/x86_64/RPM-GPG-KEY-openEuler + +[openEuler-22.03-LTS-SP4-update] +name=openEuler-22.03-LTS-SP4-update +baseurl=http://repo.openeuler.org/openEuler-22.03-LTS-SP4/update/x86_64/ +enabled=1 +gpgcheck=0 +``` + +## Installing sysSentry + +```sh +yum install sysSentry libxalarm -y +``` + +# Using sysSentry + +## Starting the Service + +```sh +systemctl start sysSentry +systemctl start xalarmd +# Verify that both services are running. +systemctl status sysSentry +systemctl status xalarmd +``` + +## Configuring Inspection Tasks + +sysSentry uses a modular approach for inspection tasks. Each module is defined by a .mod file in **/etc/sysSentry/tasks/**, containing the task runtime parameters. + +## Managing Inspection Tasks + +- Start a specified task. + +```sh +sentryctl start +``` + +- Stop a specified task. + +```sh +sentryctl stop +``` + +- View all loaded tasks and status. + +```sh +sentryctl list +``` + +Example output: + +![](figures/sentryctl_list.png) + +- Query a specified task. + +```sh +sentryctl status +``` + +Status definitions + +| Status | Meaning | +| ------- | ------------------------------------------ | +| RUNNING | Active task | +| WAITING | Periodic task awaiting next run | +| EXITED | Task not started or completed (one-shot) | +| FAILED | Task start failure or abnormal termination | + +- Reload a specified task configuration. + +```sh +sentryctl reload +``` + +- QUery the results of a specified task. + +```sh +sentryctl get_result +``` + +Results are in JSON format as follows: + +```json +{ + "result": "xxx", + "start_time": "YY-mm-DD HH:MM:SS", + "end_time": "YY-mm-DD HH:MM:SS", + "error_msg" : "xxx", + "details":{} # The details format is module-specific. +} +``` + +Result codes: + +| Code | Message | +| ------------ | ------------------------------------------------------------------------- | +| PASS | "" | +| SKIP | "not supported.maybe some rpm package not be installed." | +| FAIL | "FAILED. config may be incorrect or the command may be invalid/killed!" | +| MINOR_ALM | "the command output shows that the status is 'INFO' or 'GENERAL_WARN'." | +| MAJOR_ALM | "the command output shows that the status is 'WARN' or 'IMPORTANT_WARN'." | +| CRITICAL_ALM | "the command output shows that the status is 'FAIL' or 'EMERGENCY_WARN'." | + +# Q&A + +- Q: What happens if I see `RuntimeError: reentrant call inside <_io.BufferedWriter name=''>` in logs when I frequently start and stop sysSentry? + + A: This error appears when stopping sysSentry before it completes initialization, potentially triggering duplicate signal handlers. The error occurs if a second signal handler activates while the first one is still closing resources. While this does not impact system functionality, you are advised to wait a few seconds between starting and stopping the service to avoid this error. diff --git a/docs/en/docs/sysSentry/online-repair-plugin.md b/docs/en/docs/sysSentry/online-repair-plugin.md new file mode 100644 index 0000000000000000000000000000000000000000..90d2122efbd002943f96435d7473c107e46eeeb1 --- /dev/null +++ b/docs/en/docs/sysSentry/online-repair-plugin.md @@ -0,0 +1,98 @@ +# Online HBM ACLS/SPPR Repair Plugin + +## Introduction + +This plugin maintains system stability and operational continuity through real-time fault management. It implements online ACLS/SPPR repairs based on CE fault detection and prediction, preventing system interruptions from uncorrectable errors. The solution integrates with system firmware, IMU, BIOS, OS, and BMC components. Operating at the OS level, the plugin monitors ACLS/SPPR signals, maintains fault records, and executes repair procedures. + +## Hardware Requirements + +- AArch64 architecture +- Huawei servers with HaiyanHBM devices +- Firmware with fault address translation and OS notification capabilities +- IMU/BIOS with firmware-to-OS repair request forwarding +- BMC with repair request processing functionality + +## Installation + +### Prerequisites + +sysSentry must be installed by referring to [sysSentry Installation](./installation-and-usage.md). + +### Installing the Package + +```shell +yum install hbm_online_repair -y +``` + +## Plugin Configuration Parameters + +The default configuration path is **/etc/sysconfig/hbm_online_repair.env**. + +- Configuration Items + +| Parameter | Default | Range | Required | Description | +|-----------|---------|--------|-----------|-------------| +| HBM_ONLINE_REPAIR_LOG_LEVEL | 1 | 0-3 | Yes | Sets logging detail: 0 (DEBUG), 1 (INFO), 2 (WARNING), 3 (ERROR). Each level includes higher level logs | +| PAGE_ISOLATION_THRESHOLD | 3355443 | 0-2147483647 | Yes | Maximum system isolation resources in KB. Plugin halts isolation and repair operations when system exceeds this threshold | + +- Configuration Example + +```ini +HBM_ONLINE_REPAIR_LOG_LEVEL=1 +PAGE_ISOLATION_THRESHOLD=3355443 +``` + +## Online Repair Plugin Management + +Plugin management follows the same process as [sysSentry Installation](./installation-and-usage.md). + +Note: The `sentryctl get_result ` command returns only the plugin **start_time** and **end_time**. All other fields remain empty. To monitor plugin status and related information, check the log files. + +## Online Repair Plugin Log Viewing + +Online repair plugin logs are stored in **/var/log/sysSentry/hbm_online_repair.log**. These logs document the initial configuration and message processing results of the plugin. + +### Startup Logs + +Upon plugin startup, the log file displays entries like this: + +![](figures/hbm-start-log.png) + +### Runtime Logs + +When the plugin receives valid ACLS/SPPR fault reports, it logs **Received ACLS/SPPR repair request** and processes the information in two phases: + +![](figures/acls-example.png) + +#### Phase 1: Persistent Information Storage + +The logs show one of two outcomes: + +1. Success: **write hbm fault info to flash xxx success** +2. Failure: Other messages indicate persistence errors, as detailed below: + +| Error Message | Meaning | +|--------------|---------| +| fault info storage reach threshold, cannot save new record into flash | Storage exceeds the 128 KB threshold | +| invalid fault info | Invalid persistent data format | +| read variable xx-xx attribute failed, stop writing | Failed to read efivar attributes | +| write to xx-xx failed | Failed to write persistent data | + +#### Phase 2: Flat Mode Repairs + +The BIOS transmits ACLS/SPPR fault reports in either flat or cache mode. Repairs occur only in flat mode, with three possible outcomes: + +1. No output: Cache mode detected (only persistence storage is performed) +2. Success: **HBM ACLS/SPPR: Page xxx repair and online success** +3. Failure: Various error messages indicating specific issues: + +| Error Message | Meaning | +|--------------|---------| +| Page isolate failed: Get hardware_corrupted_size failed | Cannot access isolation resource data | +| Page isolate failed: the isolation resource is not enough | Isolation resources exhausted | +| HBM: ACLS/SPPR offline failed, address is xxx | Isolation operation failed | +| Repair driver is not loaded, skip error | Missing repair driver | +| No HBM device memory type found, skip error | No HBM device detected | +| Err addr is not in device, skip error | Address outside HBM devices | +| HBM: Address xxx is not supported to ACLS/SPPR repair | Unsupported address for repair | +| HBM ACLS/SPPR: Page xxx online failed | Page activation failed | diff --git a/docs/en/docs/sysSentry/plugins.md b/docs/en/docs/sysSentry/plugins.md new file mode 100644 index 0000000000000000000000000000000000000000..6bf965d3c2b3c4b615992063b90a5208a72012fe --- /dev/null +++ b/docs/en/docs/sysSentry/plugins.md @@ -0,0 +1,7 @@ +# Inspection Plugins + +sysSentry manages all inspection capabilities through a plugin-based architecture, where each plugin provides specific inspection functions. The current plugin suite includes: + +- CPU fault inspection: performs real-time CPU monitoring and automatically isolates faulty cores when detected. + +- Online HBM ACLS/SPPR repair: provides real-time repair capabilities for ACLS/SPPR CE/PS UEO faults. diff --git a/docs/en/docs/sysSentry/sysSentry-introduction.md b/docs/en/docs/sysSentry/sysSentry-introduction.md new file mode 100644 index 0000000000000000000000000000000000000000..30eb0c8c1b92cea8326c9dd89bd714d114ec20b2 --- /dev/null +++ b/docs/en/docs/sysSentry/sysSentry-introduction.md @@ -0,0 +1,15 @@ +# Introduction to sysSentry + +sysSentry provides a comprehensive fault inspection framework that unifies fault reporting through its northbound interface while supporting various inspection and diagnostic capabilities through southbound plugins. The framework monitors and diagnoses hardware faults across system components including CPUs, memory, drives, and NPUs. + +![System Diagram](figures/sysSentry.png) + +Key features of sysSentry include: + +1. Unified alarm and event notification: Collects fault information from plugins and manages message distribution through a centralized service. Services can selectively subscribe to specific fault notifications. + +2. Centralized logging: Consolidates fault information from all plugins in a unified logging system, streamlining problem diagnosis. + +3. Extensible diagnosis framework: Supports plugin-based inspection and diagnostic tasks. Plugins can be independently controlled (start, stop, status checks, results retrieval) and configured. The framework is language-agnostic, supporting C/C++, Python, shell, and other programming languages. + +4. Efficient data collection: Gathers hardware status information through kernel interfaces, BIOS, and BMC. The service adapts to various architectures and versions while supporting different data collection mechanisms. diff --git a/docs/en/menu/index.md b/docs/en/menu/index.md index 4656ba6f5a6e00ad159903423c6c4151564e2cf7..6a0b64913ddad23b6d82da32ff785e384f661af4 100644 --- a/docs/en/menu/index.md +++ b/docs/en/menu/index.md @@ -68,6 +68,9 @@ headless: true - [utsudo User Guide]({{< relref "./docs/memsafety/utsudo/utsudo_user_guide.md" >}}) - [Networks](#) - [Gazelle User Guide]({{< relref "./docs/Gazelle/Gazelle.md" >}}) + - [Gazelle for Redis Acceleration]({{< relref "./docs/Gazelle/Gazelle-for-redis-acceleration.md" >}}) + - [Gazelle Single-NIC User Guide]({{< relref "./docs/Gazelle/Gazelle-single-nic-user-guide.md" >}}) + - [Gazelle for openGauss Acceleration]({{< relref "./docs/Gazelle/Gazelle-for-opengauss-acceleration.md" >}}) - [Maintenance](#) - [Kernel Live Upgrade Guide]({{< relref "./docs/KernelLiveUpgrade/KernelLiveUpgrade.md" >}}) - [Installation and Deployment]({{< relref "./docs/KernelLiveUpgrade/installation-and-deployment.md" >}}) @@ -77,6 +80,11 @@ headless: true - [HA User Guide]({{< relref "./docs/thirdparty_migration/ha.md" >}}) - [Deploying an HA Cluster]({{< relref "./docs/thirdparty_migration/installing-and-deploying-HA.md" >}}) - [HA Usage Example]({{< relref "./docs/thirdparty_migration/HA_usage_examples.md" >}}) + - [sysSentry User Guide]({{< relref "./docs/sysSentry/sysSentry-introduction.md" >}}) + - [Installation and Usage]({{< relref "./docs/sysSentry/installation-and-usage.md" >}}) + - [Plugins]({{< relref "./docs/sysSentry/plugins.md" >}}) + - [CPU Fault Inspection Plugin]({{< relref "./docs/sysSentry/CPU-fault-inspection-plugin.md" >}}) + - [Online HBM ACLS/SPPR Repair Plugin]({{< relref "./docs/sysSentry/online-repair-plugin.md" >}}) - [Security](#) - [Security Hardening Guide]({{< relref "./docs/SecHarden/secHarden.md" >}}) - [OS Hardening Overview]({{< relref "./docs/SecHarden/os-hardening-overview.md" >}}) @@ -101,6 +109,7 @@ headless: true - [safeguard User Guide]({{< relref "./docs/safeguard/about-safeguard.md" >}}) - [Installation]({{< relref "./docs/safeguard/safeguard-installation.md" >}}) - [User Guide]({{< relref "./docs/safeguard/safeguard-user-guide.md" >}}) + - [SBOM]({{< relref "./docs/SBOM/SBOM.md" >}}) - [Performance](#) - [A-Tune User Guide]({{< relref "./docs/A-Tune/A-Tune.md" >}}) - [Getting to Know A-Tune]({{< relref "./docs/A-Tune/getting-to-know-a-tune.md" >}}) @@ -288,7 +297,6 @@ headless: true - [Installing the OBS Tool]({{< relref "./docs/ApplicationDev/installing-obs.md" >}}) - [openEuler Driver Development Specifications]({{< relref "./docs/Driver_Development_Specifications/openEuler-Driver-Development-Specifications.md" >}}) - [GCC for openEuler User Guide]({{< relref "./docs/GCC/overview.md" >}}) - - [GCC User Guide]({{< relref "./docs/GCC/GCC_user_guide.md" >}}) - [Kernel FDO User Guide]({{< relref "./docs/GCC/kernel_FDO_user_guide.md" >}}) - [GCC Base Performance Optimization Guide]({{< relref "./docs/GCC/GCC-base-performance-optimization-guide.md" >}}) - [GCC Toolset User Guide]({{< relref "./docs/GCC/gcc-toolset-user-guide.md" >}}) diff --git "a/docs/zh/docs/Container/iSula-shim-v2\345\257\271\346\216\245stratovirt.md" "b/docs/zh/docs/Container/iSula-shim-v2\345\257\271\346\216\245stratovirt.md" old mode 100755 new mode 100644 index 0f067c69d251862dffebb1bef4d6965cc63250a5..15a1245b96b22b2ea9b2d60cfd6cc45dfd142e1f --- "a/docs/zh/docs/Container/iSula-shim-v2\345\257\271\346\216\245stratovirt.md" +++ "b/docs/zh/docs/Container/iSula-shim-v2\345\257\271\346\216\245stratovirt.md" @@ -197,7 +197,7 @@ containerd-shim-kata-v2 使用的虚拟化组件为 StratoVirt 时，iSula 对 lsmod |grep vhost_vsock ``` - 下载对应版本和架构的 kernel 并放到 /var/lib/kata/ 路径下, 如下载 openEuler 22.03 LTS 版本 x86 架构的内核 [openeuler repo]()： + 下载对应版本和架构的 kernel 并放到 /var/lib/kata/ 路径下, 如下载 openEuler 22.03 LTS 版本 x86 架构的内核 [openeuler repo](https://repo.openeuler.org/)： ```bash cd /var/lib/kata diff --git "a/docs/zh/docs/Pin/\346\217\222\344\273\266\346\241\206\346\236\266\347\211\271\346\200\247\347\224\250\346\210\267\346\214\207\345\215\227.md" "b/docs/zh/docs/Pin/\346\217\222\344\273\266\346\241\206\346\236\266\347\211\271\346\200\247\347\224\250\346\210\267\346\214\207\345\215\227.md" old mode 100755 new mode 100644 index ef81b15744ffaa609c7910ab0818815229b23146..e27f9d0280812f3d22ba74abd7128c788cfa8934 --- "a/docs/zh/docs/Pin/\346\217\222\344\273\266\346\241\206\346\236\266\347\211\271\346\200\247\347\224\250\346\210\267\346\214\207\345\215\227.md" +++ "b/docs/zh/docs/Pin/\346\217\222\344\273\266\346\241\206\346\236\266\347\211\271\346\200\247\347\224\250\346\210\267\346\214\207\345\215\227.md" @@ -1,13 +1,22 @@ # 安装与部署 + ## 软件要求 + * 操作系统：openEuler-22.03-LTS-SP4 + ## 硬件要求 + * x86_64架构 * AArch64架构 + ## 环境准备 + * 安装openEuler系统，安装方法参考[《openEuler 安装指南》](../Installation/installation.md)。 + ### 安装依赖软件 + #### 安装插件框架GCC客户端依赖软件 + ```shell yum install -y git yum install -y make @@ -23,7 +32,9 @@ yum install -y llvm-mlir yum install -y llvm-mlir-devel yum install -y llvm-devel ``` + #### 安装插件框架服务端依赖软件 + ```shell yum install -y git yum install -y make @@ -38,18 +49,27 @@ yum install -y llvm-mlir yum install -y llvm-mlir-devel yum install -y llvm-devel ``` + ## 安装Pin + ### 安装 + #### yum安装插件框架GCC客户端 + ```shell yum install -y pin-gcc-client ``` + #### yum安装插件框架服务端 + ```shell yum install -y pin-server ``` + ### 编译构建 + #### 构建插件框架GCC客户端 + ```shell git clone https://gitee.com/openeuler/pin-gcc-client.git cd pin-gcc-client @@ -58,7 +78,9 @@ cd build cmake ../ -DMLIR_DIR=${MLIR_PATH} -DLLVM_DIR=${LLVM_PATH} make ``` + #### 构建插件框架服务端 + ```shell git clone https://gitee.com/openeuler/pin-server.git cd pin-server @@ -69,8 +91,10 @@ make ``` # 使用方法 + 用户可以通过`-fplugin`和`-fplugin-arg-libpin_xxx`使能插件工具。 命令如下： + ```shell $(TARGET): $(OBJS) $(CXX) -fplugin=${CLIENT_PATH}/libpin_gcc_client.so \ @@ -98,5 +122,7 @@ $(TARGET): $(OBJS) `-fplugin-arg-libpin_gcc_client-argN`：用户可以根据插件工具要求，指定其他参数。argN代指插件工具要求的参数字段。 # 兼容性说明 + 此节主要列出当前一些特殊场景下的兼容性问题。本项目持续迭代中，会尽快进行修复，也欢迎广大开发者加入。 + * 插件框架在`-flto`阶段使能时，不支持使用`make -j`多进程编译。建议改用`make -j1`进行编译。 diff --git a/docs/zh/docs/desktop/UKUIuserguide.md b/docs/zh/docs/desktop/UKUIuserguide.md old mode 100755 new mode 100644 index 6690ee57246ed85c8a49b7d1b3511c93d94dd5e5..ce77697369634dd15b5db89e543d1402ed67bddf --- a/docs/zh/docs/desktop/UKUIuserguide.md +++ b/docs/zh/docs/desktop/UKUIuserguide.md @@ -1,6 +1,5 @@ # UKUI 用户指南 - ## 概述 桌面是用户进行图形界面操作的基础，UKUI(UbuntuKylin UI)提供了多个功能部件，包括任务栏、开始菜单等，本文主要描述 UKUI 的使用。 @@ -15,14 +14,12 @@ 系统默认放置了计算机、回收站、主文件夹三个图标，鼠标左键双击即可打开页面，功能如下表。 - -| 图标 | 说明 | +| 图标 | 说明 | | :------------ | :------------ | | ![](./figures/icon1.png) | 计算机：显示连接到本机的驱动器和硬件| | ![](./figures/icon2.png) | 回收站：显示移除的文件| | ![](./figures/icon3.png) | 主文件夹：显示个人主目录| - 另外，右键单击“计算机”，选择“属性”，可显示当前系统版本、内核版本等相关信息。 ![图 2 “计算机”-“属性”-big](./figures/2.png) @@ -41,8 +38,6 @@ | 视图类型 | 提供四种视图类型：小图标、中图标、大图标、超大图标 | | 排序方式 | 提供根据文件名称、文件类型、文件大小、修改日期排列的四种方式| -
- ## 任务栏 ### 基本功能 @@ -51,18 +46,16 @@ ![图 4 任务栏](./figures/4.png) -| 组件 | 说明 | +| 组件 | 说明 | | :------------ | :------------ | -|![](./figures/icon4.png)| 开始菜单，用于弹出系统菜单，可查找应用和文件 | -|![](./figures/icon5.png)| 多视图切换，可在多个工作区互不干扰进行操作| -|![](./figures/icon6.png)| 文件浏览器，可浏览和管理系统中的文件| -|![](./figures/icon7.png)| Firefox网页浏览器，提供便捷安全的上网方式| -|![](./figures/icon8.png)| WPS办公套件，可以实现办公软件最常用的文字、表格、演示等多种功能| -|窗口显示区 |横条中间空白部分；显示正在运行的程序或打开的文档，可进行关闭窗口、窗口置顶操作。| -|![](./figures/icon9.png)| 托盘菜单，包含了对声音、麒麟天气、网络连接、输入法、通知中心、日期、夜间模式的设置| -|显示桌面| 按钮位于最右侧；最小化桌面的所有窗口，返回桌面；再次单击将恢复窗口| - -
+|![](./figures/icon4.png)| 开始菜单，用于弹出系统菜单，可查找应用和文件 | +|![](./figures/icon5.png)| 多视图切换，可在多个工作区互不干扰进行操作| +|![](./figures/icon6.png)| 文件浏览器，可浏览和管理系统中的文件| +|![](./figures/icon7.png)| Firefox网页浏览器，提供便捷安全的上网方式| +|![](./figures/icon8.png)| WPS办公套件，可以实现办公软件最常用的文字、表格、演示等多种功能| +|窗口显示区 |横条中间空白部分；显示正在运行的程序或打开的文档，可进行关闭窗口、窗口置顶操作。| +|![](./figures/icon9.png)| 托盘菜单，包含了对声音、麒麟天气、网络连接、输入法、通知中心、日期、夜间模式的设置| +|显示桌面| 按钮位于最右侧；最小化桌面的所有窗口，返回桌面；再次单击将恢复窗口| #### 多视图切换 @@ -102,19 +95,17 @@ ![图 11 消息收纳箱](./figures/11.png) -##### 剪切板 +##### 剪切板 剪切板可保存近期选择复制或剪切的内容，同时可通过表上说明的图标进行相应操作。 其中点击“![](./figures/icon15-o.png)”图标，可对剪切板的内容进行编辑。 -|图标| 说明| 图标 |说明 | +|图标| 说明| 图标 |说明 | | :------------ | :------------ | :------------ | :------------ | -|![](./figures/icon16.png)| 复制剪切板上的该内容 |![](./figures/icon18.png)| 编辑剪切板上的该内容 | -|![](./figures/icon17.png)| 删除剪切板上的该内容 | | | - -
- +|![](./figures/icon16.png)| 复制剪切板上的该内容 |![](./figures/icon18.png)| 编辑剪切板上的该内容 | +|![](./figures/icon17.png)| 删除剪切板上的该内容 | | | + ![图 12 剪切板](./figures/12.png) ![图 13 编辑选中实的剪切板内容](./figures/13.png) @@ -167,15 +158,13 @@ U盘插入主机后，自动读取U盘数据，点击任务栏中U盘“![](./fi 用户通过鼠标左键点击任务栏上的网络“![](./figures/icon31-o.png)”图标，可根据需要选择有线和无线两种网络连接方式。 -|图标 |说明| 图标 |说明 | +|图标 |说明| 图标 |说明 | | :------------ | :------------ | :------------ | :------------ | -|![](./figures/icon32.png)| 网络已连接 |![](./figures/icon37.png)| 网络未连接 | -|![](./figures/icon33.png)| 网络连接受限 |![](./figures/icon38.png)| 网络已上锁 | -|![](./figures/icon34.png)| 网络正在连接 |![](./figures/icon39.png)| Wifi已连接 | -|![](./figures/icon35.png)| Wifi未连接 |![](./figures/icon40.png)| Wifi连接受限 | -|![](./figures/icon36.png)| Wifi已上锁 |![](./figures/icon41.png)| Wifi正在连接 | - -
+|![](./figures/icon32.png)| 网络已连接 |![](./figures/icon37.png)| 网络未连接 | +|![](./figures/icon33.png)| 网络连接受限 |![](./figures/icon38.png)| 网络已上锁 | +|![](./figures/icon34.png)| 网络正在连接 |![](./figures/icon39.png)| Wifi已连接 | +|![](./figures/icon35.png)| Wifi未连接 |![](./figures/icon40.png)| Wifi连接受限 | +|![](./figures/icon36.png)| Wifi已上锁 |![](./figures/icon41.png)| Wifi正在连接 | ![图 22 网络连接界面](./figures/22.png) @@ -242,36 +231,28 @@ U盘插入主机后，自动读取U盘数据，点击任务栏中U盘“![](./fi 用户可对任务栏的布局进行设定，在“设置任务栏”中可进行相关设置。 -
- -## 窗口 +## 窗口 -### 窗口管理器 +### 窗口管理器 窗口管理器为用户提供了如表所示的功能。 -|功能 |说明 | +|功能 |说明 | | :--------| :----------| -|窗口标题栏| 显示当前窗口的标题名称 | -|最小化/最大化/关闭 |标题栏右侧的三个图标按钮，分别对应最小化窗口、最大化窗口、关闭窗口的功能 | -|侧边滑动 |在窗口右侧提供滑动条，可上下滚动查看页面 | -|窗口堆叠| 允许窗口之间产生重叠 | -|窗口拖拽 |在窗口标题栏长按鼠标左键，可移动窗口到任意位置 | -|窗口大小调整 |将鼠标移至窗口四角，长按左键，可任意调整窗口大小 | - -
+|窗口标题栏| 显示当前窗口的标题名称 | +|最小化/最大化/关闭 |标题栏右侧的三个图标按钮，分别对应最小化窗口、最大化窗口、关闭窗口的功能 | +|侧边滑动 |在窗口右侧提供滑动条，可上下滚动查看页面 | +|窗口堆叠| 允许窗口之间产生重叠 | +|窗口拖拽 |在窗口标题栏长按鼠标左键，可移动窗口到任意位置 | +|窗口大小调整 |将鼠标移至窗口四角，长按左键，可任意调整窗口大小 | ### 窗口切换 用户有三种方式可以切换： -* 在任务栏上点击窗口标题； +- 在任务栏上点击窗口标题； -* 在桌面上点击不同窗口； - -* 使用快捷键< Alt > + < Tab >； - -
+- 在桌面上点击不同窗口； ## 开始菜单 @@ -285,11 +266,11 @@ U盘插入主机后，自动读取U盘数据，点击任务栏中U盘“![](./fi 用户将鼠标停留在开始菜单右侧，会出现一个右侧预展开的提示栏，点击展开，即在右侧默认显示三个分类：“所有软件”、“字母分类”、“功能分类”，其中： -* 所有软件：列出所有软件，近期使用过的软件将会在此页面置顶显示。 +- 所有软件：列出所有软件，近期使用过的软件将会在此页面置顶显示。 -* 字母分类：列出系统根据首字母进行分类显示所有软件。 +- 字母分类：列出系统根据首字母进行分类显示所有软件。 -* 功能分类：列出系统根据功能进行分类显示所有软件。 +- 功能分类：列出系统根据功能进行分类显示所有软件。 用户可通过点击右上角开始菜单的全屏图标，查看全屏菜单。 @@ -359,37 +340,34 @@ U盘插入主机后，自动读取U盘数据，点击任务栏中U盘“![](./fi 各个选项说明如下表。 -|选项 |说明 | -| :------| :-------- -|固定到所有用软件 |将选中软件在所有软件列表中置顶 | -|固定到任务栏 |在任务栏上生成应用的图标 | -|添加到桌面快捷方式| 在桌面生成应用的快捷方式图标 | -|卸载| 卸载软件 | - -
+| 选项 | 说明 | +| :----------------- | :----------------------------- | +| 固定到所有用软件 | 将选中软件在所有软件列表中置顶 | +| 固定到任务栏 | 在任务栏上生成应用的图标 | +| 添加到桌面快捷方式 | 在桌面生成应用的快捷方式图标 | +| 卸载 | 卸载软件 | ## 常见问题 ### 锁屏后无法登录系统 -* 通过“Ctrl + Alt + F2”切换到字符终端。 -* 输入用户名和密码后登录。 +- 通过“Ctrl + Alt + F2”切换到字符终端。 -* 执行命令“sudo rm -rf ~/.Xauthority”。 +- 输入用户名和密码后登录。 -* 通过“Ctrl + Alt + F1”切回图形界面，输入用户密码登录。 +- 执行命令“sudo rm -rf ~/.Xauthority”。 -
+- 通过“Ctrl + Alt + F1”切回图形界面，输入用户密码登录。 ## 附录 ### 快捷键 -|快捷键 |功能 | +|快捷键 |功能 | | :------ | :----- | -|F5| 刷新桌面 | -|F1 |打开用户手册 | -|Alt + Tab |切换窗口 | -|win |打开开始菜单 | -|Ctrl + Alt + L| 锁屏 | -|Ctrl + Alt + Delete| 注销 | +|F5| 刷新桌面 | +|F1 |打开用户手册 | +|Alt + Tab |切换窗口 | +|win |打开开始菜单 | +|Ctrl + Alt + L| 锁屏 | +|Ctrl + Alt + Delete| 注销 | diff --git a/docs/zh/docs/desktop/Xfce_userguide.md b/docs/zh/docs/desktop/Xfce_userguide.md old mode 100755 new mode 100644 index d5cb867c5d6f5b42e2524a0b39cc46c9eb73b08d..4100fc799146768fb4f142a4321f3e84a9d32a8b --- a/docs/zh/docs/desktop/Xfce_userguide.md +++ b/docs/zh/docs/desktop/Xfce_userguide.md @@ -1,6 +1,5 @@ # Xfce 用户指南 - ## 一 概述 Xfce是运行在类Unix操作系统中的一款轻量级桌面环境。Xfce提供了多个功能部件，包括所有应用程序等，本文主要描述 Xfce 的使用。 @@ -9,8 +8,6 @@ Xfce是运行在类Unix操作系统中的一款轻量级桌面环境。Xfce提 ![图 1 桌面主界面-big](./figures/xfce-1.png) -
- ## 二 桌面 ### 2.1 桌面图标 @@ -39,8 +36,6 @@ Xfce是运行在类Unix操作系统中的一款轻量级桌面环境。Xfce提 | 桌面设置 | 提供关于背景、菜单、图标的设置 | | 应用程序 | 所有应用程序 | -
- ## 三 任务栏 ### 3.1 基本功能 @@ -49,7 +44,7 @@ Xfce是运行在类Unix操作系统中的一款轻量级桌面环境。Xfce提 ![图 4 任务栏](./figures/xfce-4.png) -| 组件 | 说明 | +| 组件 | 说明 | | :------------ | :------------ | | 所有应用程序 | 用于弹出所有程序以及设置，可查找应用和设置。| | 窗口显示区 | 横条中间空白部分；显示正在运行的程序或打开的文档，可进行最小化、最大化、关闭窗口、窗口置顶等操作。| @@ -148,7 +143,6 @@ Xfce是运行在类Unix操作系统中的一款轻量级桌面环境。Xfce提 ![图 21 任务栏右键菜单](./figures/xfce-861.png) - ##### 3.1.4.7 登录用户动作 用户通过鼠标左键点击任务栏上的登录用户，查看相关动作。 @@ -185,8 +179,6 @@ Xfce是运行在类Unix操作系统中的一款轻量级桌面环境。Xfce提 此时，系统会关闭所有正在运行的应用；所以，在执行此操作前，请先保存当前工作。 -
- ## 四 快捷操作栏 ### 4.1 基本功能 @@ -243,4 +235,3 @@ Xfce是运行在类Unix操作系统中的一款轻量级桌面环境。Xfce提 用户通过鼠标左键点击快捷操作栏上的“![](./figures/xfce-96.png)”图标，点击 在终端中打开，打开一个终端，当前目录为用户家目录。 ![图 30 用户家目录-big](./figures/xfce-962.png) - diff --git a/docs/zh/docs/memsafety/utshell/media/image1.png b/docs/zh/docs/memsafety/utshell/media/image1.png old mode 100755 new mode 100644 diff --git a/docs/zh/docs/memsafety/utshell/media/image2.png b/docs/zh/docs/memsafety/utshell/media/image2.png old mode 100755 new mode 100644 diff --git a/docs/zh/docs/memsafety/utshell/media/image3.png b/docs/zh/docs/memsafety/utshell/media/image3.png old mode 100755 new mode 100644 diff --git a/docs/zh/docs/memsafety/utshell/media/image4.png b/docs/zh/docs/memsafety/utshell/media/image4.png old mode 100755 new mode 100644 diff --git a/docs/zh/docs/memsafety/utshell/utshell_guide.md b/docs/zh/docs/memsafety/utshell/utshell_guide.md old mode 100755 new mode 100644