Copilot commented on code in PR #13731: URL: https://github.com/apache/trafficserver/pull/13731#discussion_r4125367624
########## doc/admin-guide/configuration/traffic-shaping.en.rst: ########## @@ -0,0 +1,299 @@ +.. 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 for `SO_MARK` look potentially inaccurate: `SO_MARK` is generally documented as requiring `CAP_NET_ADMIN` (and not `CAP_NET_RAW`). Please either correct this statement or add a more specific citation (e.g., kernel commit / versioned behavior) so operators don’t under-provision capabilities and end up with marking silently failing. ########## 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: Consider linking to GitHub’s issue template chooser (`/issues/new/choose`) instead of `/issues/new`, so reporters are guided into the right template (bug vs feature vs question) and required fields aren’t skipped. ########## STATUS: ########## @@ -88,27 +88,25 @@ Contributors looking for a mission: * Just do an egrep on "TODO" or "XXX" in the source. - * Review the bug database at: https://issues.apache.org/jira/browse/TS + * Review the open issues at: https://github.com/apache/trafficserver/issues - - Download, test and review patches attached to open bugs + - Test and review open pull requests at + https://github.com/apache/trafficserver/pulls Review Comment: The indentation/bulleting here is a bit inconsistent for a plain-text list (top-level uses `*` while the nested item uses a heavily-indented `-`). Align the indentation and bullet style with the surrounding STATUS formatting so it renders/readably scans consistently in terminals and patches. -- 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]
