Describe the per-target token bucket and the two configfs files that drive it: ratelimit_interval_ms and ratelimit_burst.
Spell out the two properties that are not obvious from the file names. The limit is accounted per message rather than per packet, so a message split into several ncfrag packets is never truncated by the bucket running dry halfway through. List both files in the target parameter table too, and qualify the rule underneath it. Only a disabled target can have its parameters updated, these two aside. Note in the message ID section that a message the bucket discards never reaches the counter, so those drops leave no gap in the IDs. Signed-off-by: Breno Leitao <[email protected]> --- Documentation/networking/netconsole.rst | 71 ++++++++++++++++++++++++++------- 1 file changed, 57 insertions(+), 14 deletions(-) diff --git a/Documentation/networking/netconsole.rst b/Documentation/networking/netconsole.rst index 4ab5d7b05cf102..9fe4888fe136b3 100644 --- a/Documentation/networking/netconsole.rst +++ b/Documentation/networking/netconsole.rst @@ -127,23 +127,26 @@ To remove a target:: The interface exposes these parameters of a netconsole target to userspace: - =============== ================================= ============ - enabled Is this target currently enabled? (read-write) - extended Extended mode enabled (read-write) - release Prepend kernel release to message (read-write) - dev_name Local network interface name (read-write) - local_port Source UDP port to use (read-write) - remote_port Remote agent's UDP port (read-write) - local_ip Source IP address to use (read-write) - remote_ip Remote agent's IP address (read-write) - local_mac Local interface's MAC address (read-only) - remote_mac Remote agent's MAC address (read-write) - transmit_errors Number of packet send errors (read-only) - =============== ================================= ============ + ===================== ================================= ============ + enabled Is this target currently enabled? (read-write) + extended Extended mode enabled (read-write) + release Prepend kernel release to message (read-write) + dev_name Local network interface name (read-write) + local_port Source UDP port to use (read-write) + remote_port Remote agent's UDP port (read-write) + local_ip Source IP address to use (read-write) + remote_ip Remote agent's IP address (read-write) + local_mac Local interface's MAC address (read-only) + remote_mac Remote agent's MAC address (read-write) + transmit_errors Number of packet send errors (read-only) + ratelimit_interval_ms Rate limit interval, milliseconds (read-write) + ratelimit_burst Messages allowed per interval (read-write) + ===================== ================================= ============ The "enabled" attribute is also used to control whether the parameters of a target can be updated or not -- you can modify the parameters of only -disabled targets (i.e. if "enabled" is 0). +disabled targets (i.e. if "enabled" is 0). The two rate limit parameters +are the exception, see `Rate limiting`_. To update a target's parameters:: @@ -177,6 +180,43 @@ You can modify these targets in runtime by creating the following targets:: cat cmdline1/remote_ip 10.0.0.3 +Rate limiting +------------- + +Netconsole hands every console message to every enabled target, so a host that +logs continuously can saturate the receiving agent. Each target carries a token +bucket that drops messages once the configured rate is exceeded, controlled by +two files in the target directory: + + ===================== ================================================ + ratelimit_interval_ms Length of the accounting interval, in + milliseconds. Zero, the default, sends + everything. + ratelimit_burst Messages allowed per interval. Defaults to + 10; zero drops every message once an + interval is set. + ===================== ================================================ + +Unlike most target parameters, both knobs can be written while the target is +enabled, which is when a flooding target most likely needs them. Either write +restarts the interval with a full burst, so a new limit applies from that +moment on. + +The limit is applied per message, not per packet, so a message big enough to be +split into several `ncfrag` packets is either sent whole or not at all. + +Crash output bypasses the bucket. Every message is sent while a panic is in +progress, and an oops or a BUG() turns the limit off for the rest of the boot, +so a small burst cannot cost you part of a crash dump. + +A drop leaves nothing on the wire. On an extended target it shows up as a gap +in the sequence number the header carries; a basic target has no such marker. + +Capping a target at 500 messages a minute:: + + echo 60000 > ratelimit_interval_ms + echo 500 > ratelimit_burst + Append User Data ---------------- @@ -359,6 +399,9 @@ indicate that a message was dropped during transmission, as it may never have been sent via netconsole. The message ID, on the other hand, is only assigned to messages that are actually transmitted via netconsole. +A message the target's rate limit discards is dropped before the ID is +assigned, so those drops leave no gap in the sequence of IDs either. + Example:: echo "This is message #1" > /dev/kmsg -- 2.53.0-Meta
