diff --git a/README-en.md b/README-en.md new file mode 100644 index 0000000000000000000000000000000000000000..7be52ae7a880e4a534527288d5e96d0735b229d5 --- /dev/null +++ b/README-en.md @@ -0,0 +1,221 @@ +# oncn-bwn + +## introduce + +This feature distinguishes between online and offline services to ensure that online services are bandwidth required and network bandwidth resources are fully utilized. Specifically, the followingfeatures are provided: + +### Pod network priority can be set +#### Direction +1. You can run the bwmcli command to set the network priority of a cgroup, and the parameters that need to be specified when you run the bwmcli command are: cgrp_path and prio +2. The default priority value is 0, 0 is the online service, and -1 is the offline service. +#### Inbound +1. Set the network priority of a destination IP packet by running the bwmcli command, and the parameters that need to be specified when you run the bwmcli command are: IP +2. By default, the unconfigured IP address is considered to be an online service, and the set IP address is considered an offline service. + +### You can set bandwidth limits for offline service networks +1. The pod network bandwidth limit takes effect for all offline services, and the total bandwidth of all offline services cannot exceed the specified network bandwidth limit. +2. Set the offline service network bandwidth limit of a host/VM by executing the bwmcli command, and specify the following parameters when executing the bwmcli command: minimum bandwidth (KB/MB/GB), maximum bandwidth (KB/MB/GB) +3. When the bandwidth of the online service is lower than the set waterline, the offline service is allowed to use the maximum bandwidth, and when the online service bandwidth is higher than the set waterline, the offline service is allowed to use the minimum bandwidth. + +### You can set an online business waterline +1. Run the bwmcli command to set the waterline of the online service of a host/virtual machine, and specify the following parameters when executing the bwmcli command: waterline value (KB/MB/GB) +2. When the total bandwidth of all online services on a host is higher than the waterline, the bandwidth that can be used by offline services is limited, and conversely, when the total bandwidth of all online services on a host is lower than the waterline, the bandwidth that can be used by offline services is increased. +3. Determine whether the total bandwidth of online services exceeds or falls below the set waterline: Determines whether the total bandwidth of online services exceeds or falls below the waterline every 10 ms, and determines whether the bandwidth to be used for offline services is determined based on whether the online bandwidth is higher than the waterline within 10 ms. + +### The QoS function of enabling/de-enabling/de-enables pods is supported +1. To enable/remove the QoS function of a NIC by executing the bwmcli command, the parameters that need to be specified when executing the bwmcli command include: NIC name, and if the NIC name is not specified, all NIC on the host will be operated by default. +2. All QoS-enabled NICs on a host are treated as a whole within the implementation, i.e., sharing set waterlines and network bandwidth limits. + +## Software architecture +``` +oncn-bwm +│ bwmcli.c # bwmcli Command-line tool +│ bwmcli.h +│ CMakeLists.txt +│ LICENSE +│ README.md +│ +├─bpf # three eBPF program files implementing bandwidth management logic +│ +└─tools # offline bandwidth detection tool, based on bpftrace. +``` + +## Installation tutorial + +1. cmake . +2. make +3. mkdir -p /usr/share/bwmcli +4. install -Dpm 0500 bpf/CMakeFiles/bwm_prio_kern.dir/bwm_prio_kern.c.o /usr/share/bwmcli/bwm_prio_kern.o +5. install -Dpm 0500 bpf/CMakeFiles/bwm_tc.dir/bwm_tc.c.o /usr/share/bwmcli/bwm_tc.o +6. install -Dpm 0500 bpf/CMakeFiles/bwm_tc_i.dir/bwm_tc_i.c.o /usr/share/bwmcli/bwm_tc_i.o +7. install -Dpm 0500 bwmcli /usr/bin +8. install -Dpm 0500 tools/bwm_monitor.bt /usr/bin +9. install -Dpm 0500 tools/bwm_monitor_ingress.bt /usr/bin + +## Directions for use + +### API description +**Interface 1** + +illustrate + ``` +bwmcli –e/-d ethx enable/disable QoS functionality for a specific network interface +bwmcli –e/-d enable/disable QoS functionality for all network interfaces +bwmcli -E/-D ethx enable/disable inbound QoS functionality for a specific network interface +bwmcli –E/-D enable/disable inbound QoS functionality for all network interfaces +``` +example +``` +# bwmcli –e eth0 –e eth1 +enable eth0 success +enable eth1 success + +# bwmcli –d eth0 –d eth1 +disable eth0 success +disable eth1 success +``` + +**Interface 2** + +Description (for outbound use) + ``` +bwmcli –s path Something went wrong +bwmcli –p path please try again later +``` +example +``` +# bwmcli -s /sys/fs/cgroup/net_cls/test_online 0 +set prio success + +# bwmcli -p /sys/fs/cgroup/net_cls/test_online +prio is 0 +``` + +**Interface 3** + +Description (for inbound) + ``` +bwmcli –A 172.17.0.2 identify inbound flow for a specific IP address as offline traffic +bwmcli –R 172.17.0.2 identify inbound flow for a specific IP address as online traffic +``` +example +``` +# bwmcli –A 172.17.0.2 +AddIp 172.17.0.2 success +# bwmcli –R 172.17.0.2 +RemoveIp 172.17.0.2 success +``` + +**Interface 4** + +illustrate + ``` +bwmcli –s bandwidth Set offline bandwidth +bwmcli –p bandwidth query offline bandwidth +bwmcli –S bandwidth set inbound offline bandwidth +bwmcli –P bandwidth query inbound offline bandwidth +``` +example +``` +# bwmcli -s bandwidth 30mb,100mb +set bandwidth success +# bwmcli -S bandwidth 30mb,100mb +set bandwidth success + +# bwmcli -p bandwidth +bandwidth is 31457280(B),104857600(B) +# bwmcli -P bandwidth +bandwidth is 31457280(B),104857600(B) +``` + +**Interface 5** + +illustrate +``` +bwmcli –s waterline Set online watermark +bwmcli –p waterline query online watermark +bwmcli –S waterline set inbound online watermark +bwmcli –P waterline query inbound online watermark +``` +example +``` +# bwmcli -s waterline 20mb +set waterline success +# bwmcli -S waterline 20mb +set waterline success + +# bwmcli -p waterline +waterline is 20971520 (B) +# bwmcli -P waterline +waterline is 20971520 (B) +``` + +**Interface 6** + +illustrate +``` +bwmcli –p stats Print internal statistics information of outbound traffic +bwmcli –P stats print internal statistics information of inbound traffic +``` +example +``` +# bwmcli -p stats +offline_target_bandwidth: 104857600 +online_pkts: 982 +offline_pkts: 0 +online_rate: 28190 +offline_rate: 0 + +# bwmcli –P stats +offline_target_bandwidth: 1073741824 +online_pkts: 1150 +offline_pkts: 0 +online_rate: 27306 +offline_rate: 0 +``` + +**Interface 7** + +illustrate +``` +bwmcli –p devs Describe the enable status of all network interfaces on the system. +``` +example +``` +# bwmcli –p devs +lo : disabled +enp2s2 : disabled + +# bwmcli –P devs +lo : disabled +enp2s2 : disabled +``` + +### Typical use cases +``` +bwmcli -p devs query the current enable status of network interfaces on the system +bwmcli -s /sys/fs/cgroup/net_cls/online 0 +bwmcli -s /sys/fs/cgroup/net_cls/offline -1 +bwmcli -e eth0 enable QoS functionality for the network interface eth0 +bwmcli -s bandwidth configure 20mb for offline business bandwidth and 1gb for online business bandwidth. +bwmcli -s waterline 30mb configuration for online business waterline +bwmcli -E veth123456 enable QoS functionality for the network interface veth123456 (host side), corresponding to pod inbound traffic. +bwmcli –A 172.17.0.2 configure target IP identification for inbound offline flow +bwmcli –R 172.17.0.2 delete target IP identification for inbound offline flow +``` + +## Get involved + +1. Fork this repository +2. Create a new Feat_xxx branch +3. Submit the code +4. Pull Request Create a new pull request + +## stunt + +1. Use Readme_XXX.md to support different languages, such as Readme_en.md, Readme_zh.md +2. Gitee Official Blog blog.gitee.com +3. You can https://gitee.com/explore this address to learn about the best open source projects on Gitee +4. GVP stands for Gitee's Most Valuable Open Source Project, and it is an excellent open source project that has been comprehensively evaluated +5. The official Gitee user manual https://gitee.com/help +6. The Gitee Cover Character is a section that showcases Gitee members https://gitee.com/gitee-stars/