Copilot commented on code in PR #13731: URL: https://github.com/apache/trafficserver/pull/13731#discussion_r4125222019
########## doc/admin-guide/configuration/traffic-shaping.en.rst: ########## @@ -0,0 +1,294 @@ +.. Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + +.. include:: ../../common.defs + +.. default-domain:: cpp + +.. _admin-traffic-shaping: + +Traffic Shaping +*************** + +|TS| does not shape traffic itself. Instead, it marks the packets it sends, +and a separate traffic shaper acts on those marks. On Linux the shaper is +usually the ``tc`` command from `iproute2 +<https://wiki.linuxfoundation.org/networking/iproute2>`_, often together with +``iptables`` or ``nftables``. On BSD systems it is ALTQ, typically configured +through ``pf``. The shaper can also be a separate router or switch that +understands DSCP. This split lets you use the full feature set of the standard +tools and shape |TS| traffic together with everything else on the host or +network. + +|TS| can apply two kinds of marks: + +Packet mark (``SO_MARK``) + A 32-bit value attached to each packet inside the Linux kernel. It never + leaves the host, so the shaper must run on the same machine as |TS|. Linux + requires ``CAP_NET_ADMIN`` to set it, or ``CAP_NET_RAW`` on Linux 5.17 and + later. When |TS| is built with POSIX capability support it keeps + ``CAP_NET_ADMIN`` after switching to its unprivileged user. On platforms + without ``SO_MARK`` the setting is ignored. Review Comment: The capability requirements and the specific kernel version (“Linux 5.17 and later”) are very specific and can become stale or be questioned without a source. Recommend either adding an authoritative reference (e.g., man page / kernel docs link) for the capability/version statement, or rephrasing to avoid pinning behavior to a specific kernel version unless the docs can be kept current. ########## doc/developer-guide/index.en.rst: ########## @@ -29,9 +29,9 @@ current version. As a result, some of the sections may refer to functionality that no longer exists. If you find any such issues, you may want to submit a `bug or a -patch <https://issues.apache.org/jira/secure/CreateIssue!default.jspa?pid=12310963>`__. +patch <https://github.com/apache/trafficserver/issues/new>`__. Review Comment: This link now points to creating a new GitHub issue, but the surrounding text says “submit a bug or a patch”. Consider either (a) updating the wording to only mention filing an issue, or (b) linking “patch” to the PR workflow (e.g., pull requests page / contributing instructions) so the link matches the text. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
