From patchwork Mon Apr 27 22:01:16 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Mauro Carvalho Chehab X-Patchwork-Id: 220444 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-10.1 required=3.0 tests=DKIMWL_WL_HIGH, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, INCLUDES_PATCH, MAILING_LIST_MULTI, SIGNED_OFF_BY, SPF_HELO_NONE,SPF_PASS,USER_AGENT_GIT autolearn=unavailable autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 57F72C82A02 for ; Mon, 27 Apr 2020 22:05:17 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 2E75C2087E for ; Mon, 27 Apr 2020 22:05:17 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1588025117; bh=b6SmWk/tS2NNZD6gud57rFFy9m1IXlxDr9U59Q9cAGU=; h=From:To:Cc:Subject:Date:In-Reply-To:References:List-ID:From; b=Ri4Z6XkfsCZHcNVofS8UkH9771b1RngxSE/wJEAMn0pW3QQuWyOYroizocqqteOqo wEcvV/3fmqjHfxdZfH+MiU6rYO/peeagmHG1eT6OkZcFzAYp5w/CE8mnRm3/bUgt6M k6gVSkcexZCpnYa7HfyEIn7w/ugOdVOZSF4+judo= Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1726513AbgD0WFC (ORCPT ); Mon, 27 Apr 2020 18:05:02 -0400 Received: from mail.kernel.org ([198.145.29.99]:47986 "EHLO mail.kernel.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726303AbgD0WB6 (ORCPT ); Mon, 27 Apr 2020 18:01:58 -0400 Received: from mail.kernel.org (ip5f5ad5c5.dynamic.kabel-deutschland.de [95.90.213.197]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPSA id 461012078C; Mon, 27 Apr 2020 22:01:56 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1588024916; bh=b6SmWk/tS2NNZD6gud57rFFy9m1IXlxDr9U59Q9cAGU=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=tnWvncRzP4eIl6sQYzWo2f1ba2SWNpBAg0KpcRaCXfwoD4NSRnYmrsophdGgrnXbx weC1J4+Oqf2eKR+cktuprYWaSuaiBIX9Bv2SZe8erk+1dXQrThvnzza0Nt+rIp/qQl vC6khWj3v+3ibOKPyOU/zJ2KanYdMcrYg0l3FhTE= Received: from mchehab by mail.kernel.org with local (Exim 4.92.3) (envelope-from ) id 1jTBp4-000Ini-GS; Tue, 28 Apr 2020 00:01:54 +0200 From: Mauro Carvalho Chehab To: Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Jonathan Corbet , "David S. Miller" , Jakub Kicinski , netdev@vger.kernel.org Subject: [PATCH 01/38] docs: networking: convert caif files to ReST Date: Tue, 28 Apr 2020 00:01:16 +0200 Message-Id: <25891dfabb48810620f82b82cc3479919bf27685.1588024424.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.25.4 In-Reply-To: References: MIME-Version: 1.0 Sender: netdev-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: netdev@vger.kernel.org There are two text files for caif, plus one already converted file. Convert the two remaining ones to ReST, create a new index.rst file for CAIF, adding it to the main networking documentation index. Signed-off-by: Mauro Carvalho Chehab --- Documentation/networking/caif/caif.rst | 2 - Documentation/networking/caif/index.rst | 13 + .../caif/{Linux-CAIF.txt => linux_caif.rst} | 54 +++-- Documentation/networking/caif/spi_porting.rst | 229 ++++++++++++++++++ Documentation/networking/caif/spi_porting.txt | 208 ---------------- Documentation/networking/index.rst | 1 + drivers/net/caif/Kconfig | 2 +- 7 files changed, 281 insertions(+), 228 deletions(-) create mode 100644 Documentation/networking/caif/index.rst rename Documentation/networking/caif/{Linux-CAIF.txt => linux_caif.rst} (90%) create mode 100644 Documentation/networking/caif/spi_porting.rst delete mode 100644 Documentation/networking/caif/spi_porting.txt diff --git a/Documentation/networking/caif/caif.rst b/Documentation/networking/caif/caif.rst index 07afc8063d4d..a07213030ccf 100644 --- a/Documentation/networking/caif/caif.rst +++ b/Documentation/networking/caif/caif.rst @@ -1,5 +1,3 @@ -:orphan: - .. SPDX-License-Identifier: GPL-2.0 .. include:: diff --git a/Documentation/networking/caif/index.rst b/Documentation/networking/caif/index.rst new file mode 100644 index 000000000000..86e5b7832ec3 --- /dev/null +++ b/Documentation/networking/caif/index.rst @@ -0,0 +1,13 @@ +.. SPDX-License-Identifier: GPL-2.0 + +CAIF +==== + +Contents: + +.. toctree:: + :maxdepth: 2 + + linux_caif + caif + spi_porting diff --git a/Documentation/networking/caif/Linux-CAIF.txt b/Documentation/networking/caif/linux_caif.rst similarity index 90% rename from Documentation/networking/caif/Linux-CAIF.txt rename to Documentation/networking/caif/linux_caif.rst index 0aa4bd381bec..a0480862ab8c 100644 --- a/Documentation/networking/caif/Linux-CAIF.txt +++ b/Documentation/networking/caif/linux_caif.rst @@ -1,12 +1,19 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: + +========== Linux CAIF -=========== -copyright (C) ST-Ericsson AB 2010 -Author: Sjur Brendeland/ sjur.brandeland@stericsson.com -License terms: GNU General Public License (GPL) version 2 +========== + +Copyright |copy| ST-Ericsson AB 2010 + +:Author: Sjur Brendeland/ sjur.brandeland@stericsson.com +:License terms: GNU General Public License (GPL) version 2 Introduction ------------- +============ + CAIF is a MUX protocol used by ST-Ericsson cellular modems for communication between Modem and host. The host processes can open virtual AT channels, initiate GPRS Data connections, Video channels and Utility Channels. @@ -16,13 +23,16 @@ ST-Ericsson modems support a number of transports between modem and host. Currently, UART and Loopback are available for Linux. -Architecture: ------------- +Architecture +============ + The implementation of CAIF is divided into: + * CAIF Socket Layer and GPRS IP Interface. * CAIF Core Protocol Implementation * CAIF Link Layer, implemented as NET devices. +:: RTNL ! @@ -46,12 +56,12 @@ The implementation of CAIF is divided into: -I M P L E M E N T A T I O N -=========================== +Implementation +============== CAIF Core Protocol Layer -========================================= +------------------------ CAIF Core layer implements the CAIF protocol as defined by ST-Ericsson. It implements the CAIF protocol stack in a layered approach, where @@ -59,8 +69,11 @@ each layer described in the specification is implemented as a separate layer. The architecture is inspired by the design patterns "Protocol Layer" and "Protocol Packet". -== CAIF structure == +CAIF structure +^^^^^^^^^^^^^^ + The Core CAIF implementation contains: + - Simple implementation of CAIF. - Layered architecture (a la Streams), each layer in the CAIF specification is implemented in a separate c-file. @@ -73,7 +86,8 @@ The Core CAIF implementation contains: to the called function (except for framing layers' receive function) Layered Architecture --------------------- +==================== + The CAIF protocol can be divided into two parts: Support functions and Protocol Implementation. The support functions include: @@ -112,7 +126,7 @@ The CAIF Protocol implementation contains: - CFSERL CAIF Serial layer. Handles concatenation/split of frames into CAIF Frames with correct length. - +:: +---------+ | Config | @@ -143,18 +157,24 @@ The CAIF Protocol implementation contains: In this layered approach the following "rules" apply. + - All layers embed the same structure "struct cflayer" - A layer does not depend on any other layer's private data. - - Layers are stacked by setting the pointers + - Layers are stacked by setting the pointers:: + layer->up , layer->dn - - In order to send data upwards, each layer should do + + - In order to send data upwards, each layer should do:: + layer->up->receive(layer->up, packet); - - In order to send data downwards, each layer should do + + - In order to send data downwards, each layer should do:: + layer->dn->transmit(layer->dn, packet); CAIF Socket and IP interface -=========================== +============================ The IP interface and CAIF socket API are implemented on top of the CAIF Core protocol. The IP Interface and CAIF socket have an instance of diff --git a/Documentation/networking/caif/spi_porting.rst b/Documentation/networking/caif/spi_porting.rst new file mode 100644 index 000000000000..d49f874b20ac --- /dev/null +++ b/Documentation/networking/caif/spi_porting.rst @@ -0,0 +1,229 @@ +.. SPDX-License-Identifier: GPL-2.0 + +================ +CAIF SPI porting +================ + +CAIF SPI basics +=============== + +Running CAIF over SPI needs some extra setup, owing to the nature of SPI. +Two extra GPIOs have been added in order to negotiate the transfers +between the master and the slave. The minimum requirement for running +CAIF over SPI is a SPI slave chip and two GPIOs (more details below). +Please note that running as a slave implies that you need to keep up +with the master clock. An overrun or underrun event is fatal. + +CAIF SPI framework +================== + +To make porting as easy as possible, the CAIF SPI has been divided in +two parts. The first part (called the interface part) deals with all +generic functionality such as length framing, SPI frame negotiation +and SPI frame delivery and transmission. The other part is the CAIF +SPI slave device part, which is the module that you have to write if +you want to run SPI CAIF on a new hardware. This part takes care of +the physical hardware, both with regard to SPI and to GPIOs. + +- Implementing a CAIF SPI device: + + - Functionality provided by the CAIF SPI slave device: + + In order to implement a SPI device you will, as a minimum, + need to implement the following + functions: + + :: + + int (*init_xfer) (struct cfspi_xfer * xfer, struct cfspi_dev *dev): + + This function is called by the CAIF SPI interface to give + you a chance to set up your hardware to be ready to receive + a stream of data from the master. The xfer structure contains + both physical and logical addresses, as well as the total length + of the transfer in both directions.The dev parameter can be used + to map to different CAIF SPI slave devices. + + :: + + void (*sig_xfer) (bool xfer, struct cfspi_dev *dev): + + This function is called by the CAIF SPI interface when the output + (SPI_INT) GPIO needs to change state. The boolean value of the xfer + variable indicates whether the GPIO should be asserted (HIGH) or + deasserted (LOW). The dev parameter can be used to map to different CAIF + SPI slave devices. + + - Functionality provided by the CAIF SPI interface: + + :: + + void (*ss_cb) (bool assert, struct cfspi_ifc *ifc); + + This function is called by the CAIF SPI slave device in order to + signal a change of state of the input GPIO (SS) to the interface. + Only active edges are mandatory to be reported. + This function can be called from IRQ context (recommended in order + not to introduce latency). The ifc parameter should be the pointer + returned from the platform probe function in the SPI device structure. + + :: + + void (*xfer_done_cb) (struct cfspi_ifc *ifc); + + This function is called by the CAIF SPI slave device in order to + report that a transfer is completed. This function should only be + called once both the transmission and the reception are completed. + This function can be called from IRQ context (recommended in order + not to introduce latency). The ifc parameter should be the pointer + returned from the platform probe function in the SPI device structure. + + - Connecting the bits and pieces: + + - Filling in the SPI slave device structure: + + Connect the necessary callback functions. + + Indicate clock speed (used to calculate toggle delays). + + Chose a suitable name (helps debugging if you use several CAIF + SPI slave devices). + + Assign your private data (can be used to map to your + structure). + + - Filling in the SPI slave platform device structure: + + Add name of driver to connect to ("cfspi_sspi"). + + Assign the SPI slave device structure as platform data. + +Padding +======= + +In order to optimize throughput, a number of SPI padding options are provided. +Padding can be enabled independently for uplink and downlink transfers. +Padding can be enabled for the head, the tail and for the total frame size. +The padding needs to be correctly configured on both sides of the link. +The padding can be changed via module parameters in cfspi_sspi.c or via +the sysfs directory of the cfspi_sspi driver (before device registration). + +- CAIF SPI device template:: + + /* + * Copyright (C) ST-Ericsson AB 2010 + * Author: Daniel Martensson / Daniel.Martensson@stericsson.com + * License terms: GNU General Public License (GPL), version 2. + * + */ + + #include + #include + #include + #include + #include + #include + #include + + MODULE_LICENSE("GPL"); + + struct sspi_struct { + struct cfspi_dev sdev; + struct cfspi_xfer *xfer; + }; + + static struct sspi_struct slave; + static struct platform_device slave_device; + + static irqreturn_t sspi_irq(int irq, void *arg) + { + /* You only need to trigger on an edge to the active state of the + * SS signal. Once a edge is detected, the ss_cb() function should be + * called with the parameter assert set to true. It is OK + * (and even advised) to call the ss_cb() function in IRQ context in + * order not to add any delay. */ + + return IRQ_HANDLED; + } + + static void sspi_complete(void *context) + { + /* Normally the DMA or the SPI framework will call you back + * in something similar to this. The only thing you need to + * do is to call the xfer_done_cb() function, providing the pointer + * to the CAIF SPI interface. It is OK to call this function + * from IRQ context. */ + } + + static int sspi_init_xfer(struct cfspi_xfer *xfer, struct cfspi_dev *dev) + { + /* Store transfer info. For a normal implementation you should + * set up your DMA here and make sure that you are ready to + * receive the data from the master SPI. */ + + struct sspi_struct *sspi = (struct sspi_struct *)dev->priv; + + sspi->xfer = xfer; + + return 0; + } + + void sspi_sig_xfer(bool xfer, struct cfspi_dev *dev) + { + /* If xfer is true then you should assert the SPI_INT to indicate to + * the master that you are ready to receive the data from the master + * SPI. If xfer is false then you should de-assert SPI_INT to indicate + * that the transfer is done. + */ + + struct sspi_struct *sspi = (struct sspi_struct *)dev->priv; + } + + static void sspi_release(struct device *dev) + { + /* + * Here you should release your SPI device resources. + */ + } + + static int __init sspi_init(void) + { + /* Here you should initialize your SPI device by providing the + * necessary functions, clock speed, name and private data. Once + * done, you can register your device with the + * platform_device_register() function. This function will return + * with the CAIF SPI interface initialized. This is probably also + * the place where you should set up your GPIOs, interrupts and SPI + * resources. */ + + int res = 0; + + /* Initialize slave device. */ + slave.sdev.init_xfer = sspi_init_xfer; + slave.sdev.sig_xfer = sspi_sig_xfer; + slave.sdev.clk_mhz = 13; + slave.sdev.priv = &slave; + slave.sdev.name = "spi_sspi"; + slave_device.dev.release = sspi_release; + + /* Initialize platform device. */ + slave_device.name = "cfspi_sspi"; + slave_device.dev.platform_data = &slave.sdev; + + /* Register platform device. */ + res = platform_device_register(&slave_device); + if (res) { + printk(KERN_WARNING "sspi_init: failed to register dev.\n"); + return -ENODEV; + } + + return res; + } + + static void __exit sspi_exit(void) + { + platform_device_del(&slave_device); + } + + module_init(sspi_init); + module_exit(sspi_exit); diff --git a/Documentation/networking/caif/spi_porting.txt b/Documentation/networking/caif/spi_porting.txt deleted file mode 100644 index 9efd0687dc4c..000000000000 --- a/Documentation/networking/caif/spi_porting.txt +++ /dev/null @@ -1,208 +0,0 @@ -- CAIF SPI porting - - -- CAIF SPI basics: - -Running CAIF over SPI needs some extra setup, owing to the nature of SPI. -Two extra GPIOs have been added in order to negotiate the transfers - between the master and the slave. The minimum requirement for running -CAIF over SPI is a SPI slave chip and two GPIOs (more details below). -Please note that running as a slave implies that you need to keep up -with the master clock. An overrun or underrun event is fatal. - -- CAIF SPI framework: - -To make porting as easy as possible, the CAIF SPI has been divided in -two parts. The first part (called the interface part) deals with all -generic functionality such as length framing, SPI frame negotiation -and SPI frame delivery and transmission. The other part is the CAIF -SPI slave device part, which is the module that you have to write if -you want to run SPI CAIF on a new hardware. This part takes care of -the physical hardware, both with regard to SPI and to GPIOs. - -- Implementing a CAIF SPI device: - - - Functionality provided by the CAIF SPI slave device: - - In order to implement a SPI device you will, as a minimum, - need to implement the following - functions: - - int (*init_xfer) (struct cfspi_xfer * xfer, struct cfspi_dev *dev): - - This function is called by the CAIF SPI interface to give - you a chance to set up your hardware to be ready to receive - a stream of data from the master. The xfer structure contains - both physical and logical addresses, as well as the total length - of the transfer in both directions.The dev parameter can be used - to map to different CAIF SPI slave devices. - - void (*sig_xfer) (bool xfer, struct cfspi_dev *dev): - - This function is called by the CAIF SPI interface when the output - (SPI_INT) GPIO needs to change state. The boolean value of the xfer - variable indicates whether the GPIO should be asserted (HIGH) or - deasserted (LOW). The dev parameter can be used to map to different CAIF - SPI slave devices. - - - Functionality provided by the CAIF SPI interface: - - void (*ss_cb) (bool assert, struct cfspi_ifc *ifc); - - This function is called by the CAIF SPI slave device in order to - signal a change of state of the input GPIO (SS) to the interface. - Only active edges are mandatory to be reported. - This function can be called from IRQ context (recommended in order - not to introduce latency). The ifc parameter should be the pointer - returned from the platform probe function in the SPI device structure. - - void (*xfer_done_cb) (struct cfspi_ifc *ifc); - - This function is called by the CAIF SPI slave device in order to - report that a transfer is completed. This function should only be - called once both the transmission and the reception are completed. - This function can be called from IRQ context (recommended in order - not to introduce latency). The ifc parameter should be the pointer - returned from the platform probe function in the SPI device structure. - - - Connecting the bits and pieces: - - - Filling in the SPI slave device structure: - - Connect the necessary callback functions. - Indicate clock speed (used to calculate toggle delays). - Chose a suitable name (helps debugging if you use several CAIF - SPI slave devices). - Assign your private data (can be used to map to your structure). - - - Filling in the SPI slave platform device structure: - Add name of driver to connect to ("cfspi_sspi"). - Assign the SPI slave device structure as platform data. - -- Padding: - -In order to optimize throughput, a number of SPI padding options are provided. -Padding can be enabled independently for uplink and downlink transfers. -Padding can be enabled for the head, the tail and for the total frame size. -The padding needs to be correctly configured on both sides of the link. -The padding can be changed via module parameters in cfspi_sspi.c or via -the sysfs directory of the cfspi_sspi driver (before device registration). - -- CAIF SPI device template: - -/* - * Copyright (C) ST-Ericsson AB 2010 - * Author: Daniel Martensson / Daniel.Martensson@stericsson.com - * License terms: GNU General Public License (GPL), version 2. - * - */ - -#include -#include -#include -#include -#include -#include -#include - -MODULE_LICENSE("GPL"); - -struct sspi_struct { - struct cfspi_dev sdev; - struct cfspi_xfer *xfer; -}; - -static struct sspi_struct slave; -static struct platform_device slave_device; - -static irqreturn_t sspi_irq(int irq, void *arg) -{ - /* You only need to trigger on an edge to the active state of the - * SS signal. Once a edge is detected, the ss_cb() function should be - * called with the parameter assert set to true. It is OK - * (and even advised) to call the ss_cb() function in IRQ context in - * order not to add any delay. */ - - return IRQ_HANDLED; -} - -static void sspi_complete(void *context) -{ - /* Normally the DMA or the SPI framework will call you back - * in something similar to this. The only thing you need to - * do is to call the xfer_done_cb() function, providing the pointer - * to the CAIF SPI interface. It is OK to call this function - * from IRQ context. */ -} - -static int sspi_init_xfer(struct cfspi_xfer *xfer, struct cfspi_dev *dev) -{ - /* Store transfer info. For a normal implementation you should - * set up your DMA here and make sure that you are ready to - * receive the data from the master SPI. */ - - struct sspi_struct *sspi = (struct sspi_struct *)dev->priv; - - sspi->xfer = xfer; - - return 0; -} - -void sspi_sig_xfer(bool xfer, struct cfspi_dev *dev) -{ - /* If xfer is true then you should assert the SPI_INT to indicate to - * the master that you are ready to receive the data from the master - * SPI. If xfer is false then you should de-assert SPI_INT to indicate - * that the transfer is done. - */ - - struct sspi_struct *sspi = (struct sspi_struct *)dev->priv; -} - -static void sspi_release(struct device *dev) -{ - /* - * Here you should release your SPI device resources. - */ -} - -static int __init sspi_init(void) -{ - /* Here you should initialize your SPI device by providing the - * necessary functions, clock speed, name and private data. Once - * done, you can register your device with the - * platform_device_register() function. This function will return - * with the CAIF SPI interface initialized. This is probably also - * the place where you should set up your GPIOs, interrupts and SPI - * resources. */ - - int res = 0; - - /* Initialize slave device. */ - slave.sdev.init_xfer = sspi_init_xfer; - slave.sdev.sig_xfer = sspi_sig_xfer; - slave.sdev.clk_mhz = 13; - slave.sdev.priv = &slave; - slave.sdev.name = "spi_sspi"; - slave_device.dev.release = sspi_release; - - /* Initialize platform device. */ - slave_device.name = "cfspi_sspi"; - slave_device.dev.platform_data = &slave.sdev; - - /* Register platform device. */ - res = platform_device_register(&slave_device); - if (res) { - printk(KERN_WARNING "sspi_init: failed to register dev.\n"); - return -ENODEV; - } - - return res; -} - -static void __exit sspi_exit(void) -{ - platform_device_del(&slave_device); -} - -module_init(sspi_init); -module_exit(sspi_exit); diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst index 6538ede29661..5b3421ec25ec 100644 --- a/Documentation/networking/index.rst +++ b/Documentation/networking/index.rst @@ -15,6 +15,7 @@ Contents: device_drivers/index dsa/index devlink/index + caif/index ethtool-netlink ieee802154 j1939 diff --git a/drivers/net/caif/Kconfig b/drivers/net/caif/Kconfig index 9db0570c5beb..1f2f2e8209c3 100644 --- a/drivers/net/caif/Kconfig +++ b/drivers/net/caif/Kconfig @@ -28,7 +28,7 @@ config CAIF_SPI_SLAVE The CAIF Link layer SPI Protocol driver for Slave SPI interface. This driver implements a platform driver to accommodate for a platform specific SPI device. A sample CAIF SPI Platform device is - provided in . + provided in . config CAIF_SPI_SYNC bool "Next command and length in start of frame" From patchwork Mon Apr 27 22:01:22 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Mauro Carvalho Chehab X-Patchwork-Id: 220440 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-10.1 required=3.0 tests=DKIMWL_WL_HIGH, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, INCLUDES_PATCH, MAILING_LIST_MULTI, SIGNED_OFF_BY, SPF_HELO_NONE,SPF_PASS,USER_AGENT_GIT autolearn=unavailable autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 726F9C82A01 for ; Mon, 27 Apr 2020 22:06:03 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 4F40A20575 for ; Mon, 27 Apr 2020 22:06:03 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1588025163; bh=sAZ/O2zdcyNp3hYa0dOFdYg2wRWDs461rvytxvnBq+Y=; h=From:To:Cc:Subject:Date:In-Reply-To:References:List-ID:From; b=njXgWwLShc9qN1sdOHeSm5+DffplJjN622Q15NoZO3DWHkyo53tGqawQhi5mkw9an Zmi2GWzui/g8gVuRzDANTMAu7VnKFy5m/sBt6n+gvGfC1V1nyg9DdAP2ozj2WmyQIk fxcCPRJe7V39U9xLB0wll1Qj72q5zwOTZ5twApeQ= Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1727045AbgD0WF7 (ORCPT ); Mon, 27 Apr 2020 18:05:59 -0400 Received: from mail.kernel.org ([198.145.29.99]:47636 "EHLO mail.kernel.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726233AbgD0WB5 (ORCPT ); Mon, 27 Apr 2020 18:01:57 -0400 Received: from mail.kernel.org (ip5f5ad5c5.dynamic.kabel-deutschland.de [95.90.213.197]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPSA id 5984321835; Mon, 27 Apr 2020 22:01:56 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1588024916; bh=sAZ/O2zdcyNp3hYa0dOFdYg2wRWDs461rvytxvnBq+Y=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=XYDgAAeD1+15BIN62/BImoK2Ig+LC4dVMR7YfXZZzXiZGDyuJ1GoXtE/plxwV8Lm/ BrBIwZqnFnV9lbNc8TQ7pqGefBV1KfnuBCl0p5iM5AvV3x3mV/M+bBqPoiG0YDmCoL vylwBr2nURCLVh04/DewtEOiv2GXzpM0rKlOtXAo= Received: from mchehab by mail.kernel.org with local (Exim 4.92.3) (envelope-from ) id 1jTBp4-000IoB-LU; Tue, 28 Apr 2020 00:01:54 +0200 From: Mauro Carvalho Chehab To: Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Jonathan Corbet , "David S. Miller" , Jakub Kicinski , Ralf Baechle , netdev@vger.kernel.org, linux-hams@vger.kernel.org Subject: [PATCH 07/38] docs: networking: convert ax25.txt to ReST Date: Tue, 28 Apr 2020 00:01:22 +0200 Message-Id: X-Mailer: git-send-email 2.25.4 In-Reply-To: References: MIME-Version: 1.0 Sender: netdev-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: netdev@vger.kernel.org There isn't much to be done here. Just: - add SPDX header; - add a document title. Signed-off-by: Mauro Carvalho Chehab --- Documentation/networking/{ax25.txt => ax25.rst} | 6 ++++++ Documentation/networking/index.rst | 1 + net/ax25/Kconfig | 6 +++--- 3 files changed, 10 insertions(+), 3 deletions(-) rename Documentation/networking/{ax25.txt => ax25.rst} (91%) diff --git a/Documentation/networking/ax25.txt b/Documentation/networking/ax25.rst similarity index 91% rename from Documentation/networking/ax25.txt rename to Documentation/networking/ax25.rst index 8257dbf9be57..824afd7002db 100644 --- a/Documentation/networking/ax25.txt +++ b/Documentation/networking/ax25.rst @@ -1,3 +1,9 @@ +.. SPDX-License-Identifier: GPL-2.0 + +===== +AX.25 +===== + To use the amateur radio protocols within Linux you will need to get a suitable copy of the AX.25 Utilities. More detailed information about AX.25, NET/ROM and ROSE, associated programs and and utilities can be diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst index 841f3c3905d5..6a5858b27cf6 100644 --- a/Documentation/networking/index.rst +++ b/Documentation/networking/index.rst @@ -42,6 +42,7 @@ Contents: arcnet-hardware arcnet atm + ax25 .. only:: subproject and html diff --git a/net/ax25/Kconfig b/net/ax25/Kconfig index 043fd5437809..97d686d115c0 100644 --- a/net/ax25/Kconfig +++ b/net/ax25/Kconfig @@ -40,7 +40,7 @@ config AX25 radio as well as information about how to configure an AX.25 port is contained in the AX25-HOWTO, available from . You might also want to - check out the file in the + check out the file in the kernel source. More information about digital amateur radio in general is on the WWW at . @@ -88,7 +88,7 @@ config NETROM users as well as information about how to configure an AX.25 port is contained in the Linux Ham Wiki, available from . You also might want to check out the - file . More information about + file . More information about digital amateur radio in general is on the WWW at . @@ -107,7 +107,7 @@ config ROSE users as well as information about how to configure an AX.25 port is contained in the Linux Ham Wiki, available from . You also might want to check out the - file . More information about + file . More information about digital amateur radio in general is on the WWW at . From patchwork Mon Apr 27 22:01:24 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Mauro Carvalho Chehab X-Patchwork-Id: 220458 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-10.1 required=3.0 tests=DKIMWL_WL_HIGH, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, INCLUDES_PATCH, MAILING_LIST_MULTI, SIGNED_OFF_BY, SPF_HELO_NONE, SPF_PASS, USER_AGENT_GIT autolearn=ham autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id F0C7EC82A00 for ; Mon, 27 Apr 2020 22:02:10 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id A7A5E2078C for ; Mon, 27 Apr 2020 22:02:09 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1588024930; bh=xxN6APHaqJl4kkyZpYkfCgEVb/bPQ9wvvkv/aTl4BEw=; h=From:To:Cc:Subject:Date:In-Reply-To:References:List-ID:From; b=Na0WMncmTbehW0m/IOXBm/7+BvZJ71RqsuYib4Hk2J8qM7gZojkvIF7nRMiwlpDPT MVIQDm3+oS2ARmG5IOvQZOas7DxUAzKkvOoO+/JomiRVqCy6m8FRjvJ3Z/T3/V3BDX MgjESk/I+Pj991fOgEMYAuToKKs3VH1ogha43oYE= Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1726503AbgD0WCI (ORCPT ); Mon, 27 Apr 2020 18:02:08 -0400 Received: from mail.kernel.org ([198.145.29.99]:48144 "EHLO mail.kernel.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726396AbgD0WCF (ORCPT ); Mon, 27 Apr 2020 18:02:05 -0400 Received: from mail.kernel.org (ip5f5ad5c5.dynamic.kabel-deutschland.de [95.90.213.197]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPSA id 7F31C21974; Mon, 27 Apr 2020 22:01:56 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1588024917; bh=xxN6APHaqJl4kkyZpYkfCgEVb/bPQ9wvvkv/aTl4BEw=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=exSpkvSGHkbt2xFb0Hb2fvvVzmD786b7HXJCVqYUrnpIjhMs3e/ukrCzINGhLXNXF iPgdg+IvvK12xoXDXatxGc7wGw2Utzq1+22wBcBG0kdP++eR8ElIKmx1Iwu2BqUFnP yyTarIGMEpFeQmm4QEV6NrYF6RTXp+ddW8wHgYeQ= Received: from mchehab by mail.kernel.org with local (Exim 4.92.3) (envelope-from ) id 1jTBp4-000IoN-NY; Tue, 28 Apr 2020 00:01:54 +0200 From: Mauro Carvalho Chehab To: Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Jonathan Corbet , "David S. Miller" , Jakub Kicinski , Jeff Kirsher , netdev@vger.kernel.org, intel-wired-lan@lists.osuosl.org Subject: [PATCH 09/38] docs: networking: convert bonding.txt to ReST Date: Tue, 28 Apr 2020 00:01:24 +0200 Message-Id: <0bd4bc995477514e91e35994d3fdd2306ed7abd3.1588024424.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.25.4 In-Reply-To: References: MIME-Version: 1.0 Sender: netdev-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: netdev@vger.kernel.org - add SPDX header; - adjust titles and chapters, adding proper markups; - comment out text-only TOC from html/pdf output; - mark code blocks and literals as such; - mark tables as such; - add notes markups; - adjust identation, whitespaces and blank lines; - add to networking/index.rst. Signed-off-by: Mauro Carvalho Chehab --- .../networking/{bonding.txt => bonding.rst} | 1275 +++++++++-------- .../networking/device_drivers/intel/e100.rst | 2 +- .../networking/device_drivers/intel/ixgb.rst | 2 +- Documentation/networking/index.rst | 1 + drivers/net/Kconfig | 2 +- 5 files changed, 668 insertions(+), 614 deletions(-) rename Documentation/networking/{bonding.txt => bonding.rst} (75%) diff --git a/Documentation/networking/bonding.txt b/Documentation/networking/bonding.rst similarity index 75% rename from Documentation/networking/bonding.txt rename to Documentation/networking/bonding.rst index e3abfbd32f71..dd49f95d28d3 100644 --- a/Documentation/networking/bonding.txt +++ b/Documentation/networking/bonding.rst @@ -1,10 +1,15 @@ +.. SPDX-License-Identifier: GPL-2.0 - Linux Ethernet Bonding Driver HOWTO +=================================== +Linux Ethernet Bonding Driver HOWTO +=================================== - Latest update: 27 April 2011 +Latest update: 27 April 2011 + +Initial release: Thomas Davis + +Corrections, HA extensions: 2000/10/03-15: -Initial release : Thomas Davis -Corrections, HA extensions : 2000/10/03-15 : - Willy Tarreau - Constantine Gavrilov - Chad N. Tindel @@ -13,98 +18,98 @@ Corrections, HA extensions : 2000/10/03-15 : Reorganized and updated Feb 2005 by Jay Vosburgh Added Sysfs information: 2006/04/24 + - Mitch Williams Introduction ============ - The Linux bonding driver provides a method for aggregating +The Linux bonding driver provides a method for aggregating multiple network interfaces into a single logical "bonded" interface. The behavior of the bonded interfaces depends upon the mode; generally speaking, modes provide either hot standby or load balancing services. Additionally, link integrity monitoring may be performed. - - The bonding driver originally came from Donald Becker's + +The bonding driver originally came from Donald Becker's beowulf patches for kernel 2.0. It has changed quite a bit since, and the original tools from extreme-linux and beowulf sites will not work with this version of the driver. - For new versions of the driver, updated userspace tools, and +For new versions of the driver, updated userspace tools, and who to ask for help, please follow the links at the end of this file. -Table of Contents -================= +.. Table of Contents -1. Bonding Driver Installation + 1. Bonding Driver Installation -2. Bonding Driver Options + 2. Bonding Driver Options -3. Configuring Bonding Devices -3.1 Configuration with Sysconfig Support -3.1.1 Using DHCP with Sysconfig -3.1.2 Configuring Multiple Bonds with Sysconfig -3.2 Configuration with Initscripts Support -3.2.1 Using DHCP with Initscripts -3.2.2 Configuring Multiple Bonds with Initscripts -3.3 Configuring Bonding Manually with Ifenslave -3.3.1 Configuring Multiple Bonds Manually -3.4 Configuring Bonding Manually via Sysfs -3.5 Configuration with Interfaces Support -3.6 Overriding Configuration for Special Cases -3.7 Configuring LACP for 802.3ad mode in a more secure way + 3. Configuring Bonding Devices + 3.1 Configuration with Sysconfig Support + 3.1.1 Using DHCP with Sysconfig + 3.1.2 Configuring Multiple Bonds with Sysconfig + 3.2 Configuration with Initscripts Support + 3.2.1 Using DHCP with Initscripts + 3.2.2 Configuring Multiple Bonds with Initscripts + 3.3 Configuring Bonding Manually with Ifenslave + 3.3.1 Configuring Multiple Bonds Manually + 3.4 Configuring Bonding Manually via Sysfs + 3.5 Configuration with Interfaces Support + 3.6 Overriding Configuration for Special Cases + 3.7 Configuring LACP for 802.3ad mode in a more secure way -4. Querying Bonding Configuration -4.1 Bonding Configuration -4.2 Network Configuration + 4. Querying Bonding Configuration + 4.1 Bonding Configuration + 4.2 Network Configuration -5. Switch Configuration + 5. Switch Configuration -6. 802.1q VLAN Support + 6. 802.1q VLAN Support -7. Link Monitoring -7.1 ARP Monitor Operation -7.2 Configuring Multiple ARP Targets -7.3 MII Monitor Operation + 7. Link Monitoring + 7.1 ARP Monitor Operation + 7.2 Configuring Multiple ARP Targets + 7.3 MII Monitor Operation -8. Potential Trouble Sources -8.1 Adventures in Routing -8.2 Ethernet Device Renaming -8.3 Painfully Slow Or No Failed Link Detection By Miimon + 8. Potential Trouble Sources + 8.1 Adventures in Routing + 8.2 Ethernet Device Renaming + 8.3 Painfully Slow Or No Failed Link Detection By Miimon -9. SNMP agents + 9. SNMP agents -10. Promiscuous mode + 10. Promiscuous mode -11. Configuring Bonding for High Availability -11.1 High Availability in a Single Switch Topology -11.2 High Availability in a Multiple Switch Topology -11.2.1 HA Bonding Mode Selection for Multiple Switch Topology -11.2.2 HA Link Monitoring for Multiple Switch Topology + 11. Configuring Bonding for High Availability + 11.1 High Availability in a Single Switch Topology + 11.2 High Availability in a Multiple Switch Topology + 11.2.1 HA Bonding Mode Selection for Multiple Switch Topology + 11.2.2 HA Link Monitoring for Multiple Switch Topology -12. Configuring Bonding for Maximum Throughput -12.1 Maximum Throughput in a Single Switch Topology -12.1.1 MT Bonding Mode Selection for Single Switch Topology -12.1.2 MT Link Monitoring for Single Switch Topology -12.2 Maximum Throughput in a Multiple Switch Topology -12.2.1 MT Bonding Mode Selection for Multiple Switch Topology -12.2.2 MT Link Monitoring for Multiple Switch Topology + 12. Configuring Bonding for Maximum Throughput + 12.1 Maximum Throughput in a Single Switch Topology + 12.1.1 MT Bonding Mode Selection for Single Switch Topology + 12.1.2 MT Link Monitoring for Single Switch Topology + 12.2 Maximum Throughput in a Multiple Switch Topology + 12.2.1 MT Bonding Mode Selection for Multiple Switch Topology + 12.2.2 MT Link Monitoring for Multiple Switch Topology -13. Switch Behavior Issues -13.1 Link Establishment and Failover Delays -13.2 Duplicated Incoming Packets + 13. Switch Behavior Issues + 13.1 Link Establishment and Failover Delays + 13.2 Duplicated Incoming Packets -14. Hardware Specific Considerations -14.1 IBM BladeCenter + 14. Hardware Specific Considerations + 14.1 IBM BladeCenter -15. Frequently Asked Questions + 15. Frequently Asked Questions -16. Resources and Links + 16. Resources and Links 1. Bonding Driver Installation ============================== - Most popular distro kernels ship with the bonding driver +Most popular distro kernels ship with the bonding driver already available as a module. If your distro does not, or you have need to compile bonding from source (e.g., configuring and installing a mainline kernel from kernel.org), you'll need to perform @@ -113,54 +118,54 @@ the following steps: 1.1 Configure and build the kernel with bonding ----------------------------------------------- - The current version of the bonding driver is available in the +The current version of the bonding driver is available in the drivers/net/bonding subdirectory of the most recent kernel source (which is available on http://kernel.org). Most users "rolling their own" will want to use the most recent kernel from kernel.org. - Configure kernel with "make menuconfig" (or "make xconfig" or +Configure kernel with "make menuconfig" (or "make xconfig" or "make config"), then select "Bonding driver support" in the "Network device support" section. It is recommended that you configure the driver as module since it is currently the only way to pass parameters to the driver or configure more than one bonding device. - Build and install the new kernel and modules. +Build and install the new kernel and modules. 1.2 Bonding Control Utility -------------------------------------- +--------------------------- - It is recommended to configure bonding via iproute2 (netlink) +It is recommended to configure bonding via iproute2 (netlink) or sysfs, the old ifenslave control utility is obsolete. 2. Bonding Driver Options ========================= - Options for the bonding driver are supplied as parameters to the +Options for the bonding driver are supplied as parameters to the bonding module at load time, or are specified via sysfs. - Module options may be given as command line arguments to the +Module options may be given as command line arguments to the insmod or modprobe command, but are usually specified in either the -/etc/modprobe.d/*.conf configuration files, or in a distro-specific +``/etc/modprobe.d/*.conf`` configuration files, or in a distro-specific configuration file (some of which are detailed in the next section). - Details on bonding support for sysfs is provided in the +Details on bonding support for sysfs is provided in the "Configuring Bonding Manually via Sysfs" section, below. - The available bonding driver parameters are listed below. If a +The available bonding driver parameters are listed below. If a parameter is not specified the default value is used. When initially configuring a bond, it is recommended "tail -f /var/log/messages" be run in a separate window to watch for bonding driver error messages. - It is critical that either the miimon or arp_interval and +It is critical that either the miimon or arp_interval and arp_ip_target parameters be specified, otherwise serious network degradation will occur during link failures. Very few devices do not support at least miimon, so there is really no reason not to use it. - Options with textual values will accept either the text name +Options with textual values will accept either the text name or, for backwards compatibility, the option value. E.g., "mode=802.3ad" and "mode=4" set the same mode. - The parameters are as follows: +The parameters are as follows: active_slave @@ -246,10 +251,13 @@ ad_user_port_key In an AD system, the port-key has three parts as shown below - + ===== ============ Bits Use + ===== ============ 00 Duplex 01-05 Speed 06-15 User-defined + ===== ============ This defines the upper 10 bits of the port key. The values can be from 0 - 1023. If not given, the system defaults to 0. @@ -699,7 +707,7 @@ mode swapped with the new curr_active_slave that was chosen. -num_grat_arp +num_grat_arp, num_unsol_na Specify the number of peer notifications (gratuitous ARPs and @@ -729,13 +737,13 @@ packets_per_slave peer_notif_delay - Specify the delay, in milliseconds, between each peer - notification (gratuitous ARP and unsolicited IPv6 Neighbor - Advertisement) when they are issued after a failover event. - This delay should be a multiple of the link monitor interval - (arp_interval or miimon, whichever is active). The default - value is 0 which means to match the value of the link monitor - interval. + Specify the delay, in milliseconds, between each peer + notification (gratuitous ARP and unsolicited IPv6 Neighbor + Advertisement) when they are issued after a failover event. + This delay should be a multiple of the link monitor interval + (arp_interval or miimon, whichever is active). The default + value is 0 which means to match the value of the link monitor + interval. primary @@ -977,88 +985,88 @@ lp_interval 3. Configuring Bonding Devices ============================== - You can configure bonding using either your distro's network +You can configure bonding using either your distro's network initialization scripts, or manually using either iproute2 or the sysfs interface. Distros generally use one of three packages for the network initialization scripts: initscripts, sysconfig or interfaces. Recent versions of these packages have support for bonding, while older versions do not. - We will first describe the options for configuring bonding for +We will first describe the options for configuring bonding for distros using versions of initscripts, sysconfig and interfaces with full or partial support for bonding, then provide information on enabling bonding without support from the network initialization scripts (i.e., older versions of initscripts or sysconfig). - If you're unsure whether your distro uses sysconfig, +If you're unsure whether your distro uses sysconfig, initscripts or interfaces, or don't know if it's new enough, have no fear. Determining this is fairly straightforward. - First, look for a file called interfaces in /etc/network directory. +First, look for a file called interfaces in /etc/network directory. If this file is present in your system, then your system use interfaces. See Configuration with Interfaces Support. - Else, issue the command: +Else, issue the command:: -$ rpm -qf /sbin/ifup + $ rpm -qf /sbin/ifup - It will respond with a line of text starting with either +It will respond with a line of text starting with either "initscripts" or "sysconfig," followed by some numbers. This is the package that provides your network initialization scripts. - Next, to determine if your installation supports bonding, -issue the command: +Next, to determine if your installation supports bonding, +issue the command:: -$ grep ifenslave /sbin/ifup + $ grep ifenslave /sbin/ifup - If this returns any matches, then your initscripts or +If this returns any matches, then your initscripts or sysconfig has support for bonding. 3.1 Configuration with Sysconfig Support ---------------------------------------- - This section applies to distros using a version of sysconfig +This section applies to distros using a version of sysconfig with bonding support, for example, SuSE Linux Enterprise Server 9. - SuSE SLES 9's networking configuration system does support +SuSE SLES 9's networking configuration system does support bonding, however, at this writing, the YaST system configuration front end does not provide any means to work with bonding devices. Bonding devices can be managed by hand, however, as follows. - First, if they have not already been configured, configure the +First, if they have not already been configured, configure the slave devices. On SLES 9, this is most easily done by running the yast2 sysconfig configuration utility. The goal is for to create an ifcfg-id file for each slave device. The simplest way to accomplish this is to configure the devices for DHCP (this is only to get the file ifcfg-id file created; see below for some issues with DHCP). The -name of the configuration file for each device will be of the form: +name of the configuration file for each device will be of the form:: -ifcfg-id-xx:xx:xx:xx:xx:xx + ifcfg-id-xx:xx:xx:xx:xx:xx - Where the "xx" portion will be replaced with the digits from +Where the "xx" portion will be replaced with the digits from the device's permanent MAC address. - Once the set of ifcfg-id-xx:xx:xx:xx:xx:xx files has been +Once the set of ifcfg-id-xx:xx:xx:xx:xx:xx files has been created, it is necessary to edit the configuration files for the slave devices (the MAC addresses correspond to those of the slave devices). Before editing, the file will contain multiple lines, and will look -something like this: +something like this:: -BOOTPROTO='dhcp' -STARTMODE='on' -USERCTL='no' -UNIQUE='XNzu.WeZGOGF+4wE' -_nm_name='bus-pci-0001:61:01.0' + BOOTPROTO='dhcp' + STARTMODE='on' + USERCTL='no' + UNIQUE='XNzu.WeZGOGF+4wE' + _nm_name='bus-pci-0001:61:01.0' - Change the BOOTPROTO and STARTMODE lines to the following: +Change the BOOTPROTO and STARTMODE lines to the following:: -BOOTPROTO='none' -STARTMODE='off' + BOOTPROTO='none' + STARTMODE='off' - Do not alter the UNIQUE or _nm_name lines. Remove any other +Do not alter the UNIQUE or _nm_name lines. Remove any other lines (USERCTL, etc). - Once the ifcfg-id-xx:xx:xx:xx:xx:xx files have been modified, +Once the ifcfg-id-xx:xx:xx:xx:xx:xx files have been modified, it's time to create the configuration file for the bonding device itself. This file is named ifcfg-bondX, where X is the number of the bonding device to create, starting at 0. The first such file is @@ -1066,49 +1074,52 @@ ifcfg-bond0, the second is ifcfg-bond1, and so on. The sysconfig network configuration system will correctly start multiple instances of bonding. - The contents of the ifcfg-bondX file is as follows: +The contents of the ifcfg-bondX file is as follows:: -BOOTPROTO="static" -BROADCAST="10.0.2.255" -IPADDR="10.0.2.10" -NETMASK="255.255.0.0" -NETWORK="10.0.2.0" -REMOTE_IPADDR="" -STARTMODE="onboot" -BONDING_MASTER="yes" -BONDING_MODULE_OPTS="mode=active-backup miimon=100" -BONDING_SLAVE0="eth0" -BONDING_SLAVE1="bus-pci-0000:06:08.1" + BOOTPROTO="static" + BROADCAST="10.0.2.255" + IPADDR="10.0.2.10" + NETMASK="255.255.0.0" + NETWORK="10.0.2.0" + REMOTE_IPADDR="" + STARTMODE="onboot" + BONDING_MASTER="yes" + BONDING_MODULE_OPTS="mode=active-backup miimon=100" + BONDING_SLAVE0="eth0" + BONDING_SLAVE1="bus-pci-0000:06:08.1" - Replace the sample BROADCAST, IPADDR, NETMASK and NETWORK +Replace the sample BROADCAST, IPADDR, NETMASK and NETWORK values with the appropriate values for your network. - The STARTMODE specifies when the device is brought online. +The STARTMODE specifies when the device is brought online. The possible values are: - onboot: The device is started at boot time. If you're not + ======== ====================================================== + onboot The device is started at boot time. If you're not sure, this is probably what you want. - manual: The device is started only when ifup is called + manual The device is started only when ifup is called manually. Bonding devices may be configured this way if you do not wish them to start automatically at boot for some reason. - hotplug: The device is started by a hotplug event. This is not + hotplug The device is started by a hotplug event. This is not a valid choice for a bonding device. - off or ignore: The device configuration is ignored. + off or The device configuration is ignored. + ignore + ======== ====================================================== - The line BONDING_MASTER='yes' indicates that the device is a +The line BONDING_MASTER='yes' indicates that the device is a bonding master device. The only useful value is "yes." - The contents of BONDING_MODULE_OPTS are supplied to the +The contents of BONDING_MODULE_OPTS are supplied to the instance of the bonding module for this device. Specify the options for the bonding mode, link monitoring, and so on here. Do not include the max_bonds bonding parameter; this will confuse the configuration system if you have multiple bonding devices. - Finally, supply one BONDING_SLAVEn="slave device" for each +Finally, supply one BONDING_SLAVEn="slave device" for each slave. where "n" is an increasing value, one for each slave. The "slave device" is either an interface name, e.g., "eth0", or a device specifier for the network device. The interface name is easier to @@ -1120,34 +1131,34 @@ changes (for example, it is moved from one PCI slot to another). The example above uses one of each type for demonstration purposes; most configurations will choose one or the other for all slave devices. - When all configuration files have been modified or created, +When all configuration files have been modified or created, networking must be restarted for the configuration changes to take -effect. This can be accomplished via the following: +effect. This can be accomplished via the following:: -# /etc/init.d/network restart + # /etc/init.d/network restart - Note that the network control script (/sbin/ifdown) will +Note that the network control script (/sbin/ifdown) will remove the bonding module as part of the network shutdown processing, so it is not necessary to remove the module by hand if, e.g., the module parameters have changed. - Also, at this writing, YaST/YaST2 will not manage bonding +Also, at this writing, YaST/YaST2 will not manage bonding devices (they do not show bonding interfaces on its list of network devices). It is necessary to edit the configuration file by hand to change the bonding configuration. - Additional general options and details of the ifcfg file -format can be found in an example ifcfg template file: +Additional general options and details of the ifcfg file +format can be found in an example ifcfg template file:: -/etc/sysconfig/network/ifcfg.template + /etc/sysconfig/network/ifcfg.template - Note that the template does not document the various BONDING_ +Note that the template does not document the various ``BONDING_*`` settings described above, but does describe many of the other options. 3.1.1 Using DHCP with Sysconfig ------------------------------- - Under sysconfig, configuring a device with BOOTPROTO='dhcp' +Under sysconfig, configuring a device with BOOTPROTO='dhcp' will cause it to query DHCP for its IP address information. At this writing, this does not function for bonding devices; the scripts attempt to obtain the device address from DHCP prior to adding any of @@ -1157,7 +1168,7 @@ sent to the network. 3.1.2 Configuring Multiple Bonds with Sysconfig ----------------------------------------------- - The sysconfig network initialization system is capable of +The sysconfig network initialization system is capable of handling multiple bonding devices. All that is necessary is for each bonding instance to have an appropriately configured ifcfg-bondX file (as described above). Do not specify the "max_bonds" parameter to any @@ -1165,14 +1176,14 @@ instance of bonding, as this will confuse sysconfig. If you require multiple bonding devices with identical parameters, create multiple ifcfg-bondX files. - Because the sysconfig scripts supply the bonding module +Because the sysconfig scripts supply the bonding module options in the ifcfg-bondX file, it is not necessary to add them to -the system /etc/modules.d/*.conf configuration files. +the system ``/etc/modules.d/*.conf`` configuration files. 3.2 Configuration with Initscripts Support ------------------------------------------ - This section applies to distros using a recent version of +This section applies to distros using a recent version of initscripts with bonding support, for example, Red Hat Enterprise Linux version 3 or later, Fedora, etc. On these systems, the network initialization scripts have knowledge of bonding, and can be configured to @@ -1180,7 +1191,7 @@ control bonding devices. Note that older versions of the initscripts package have lower levels of support for bonding; this will be noted where applicable. - These distros will not automatically load the network adapter +These distros will not automatically load the network adapter driver unless the ethX device is configured with an IP address. Because of this constraint, users must manually configure a network-script file for all physical adapters that will be members of @@ -1188,19 +1199,19 @@ a bondX link. Network script files are located in the directory: /etc/sysconfig/network-scripts - The file name must be prefixed with "ifcfg-eth" and suffixed +The file name must be prefixed with "ifcfg-eth" and suffixed with the adapter's physical adapter number. For example, the script for eth0 would be named /etc/sysconfig/network-scripts/ifcfg-eth0. -Place the following text in the file: +Place the following text in the file:: -DEVICE=eth0 -USERCTL=no -ONBOOT=yes -MASTER=bond0 -SLAVE=yes -BOOTPROTO=none + DEVICE=eth0 + USERCTL=no + ONBOOT=yes + MASTER=bond0 + SLAVE=yes + BOOTPROTO=none - The DEVICE= line will be different for every ethX device and +The DEVICE= line will be different for every ethX device and must correspond with the name of the file, i.e., ifcfg-eth1 must have a device line of DEVICE=eth1. The setting of the MASTER= line will also depend on the final bonding interface name chosen for your bond. @@ -1208,69 +1219,70 @@ As with other network devices, these typically start at 0, and go up one for each device, i.e., the first bonding instance is bond0, the second is bond1, and so on. - Next, create a bond network script. The file name for this +Next, create a bond network script. The file name for this script will be /etc/sysconfig/network-scripts/ifcfg-bondX where X is the number of the bond. For bond0 the file is named "ifcfg-bond0", for bond1 it is named "ifcfg-bond1", and so on. Within that file, -place the following text: +place the following text:: -DEVICE=bond0 -IPADDR=192.168.1.1 -NETMASK=255.255.255.0 -NETWORK=192.168.1.0 -BROADCAST=192.168.1.255 -ONBOOT=yes -BOOTPROTO=none -USERCTL=no + DEVICE=bond0 + IPADDR=192.168.1.1 + NETMASK=255.255.255.0 + NETWORK=192.168.1.0 + BROADCAST=192.168.1.255 + ONBOOT=yes + BOOTPROTO=none + USERCTL=no - Be sure to change the networking specific lines (IPADDR, +Be sure to change the networking specific lines (IPADDR, NETMASK, NETWORK and BROADCAST) to match your network configuration. - For later versions of initscripts, such as that found with Fedora +For later versions of initscripts, such as that found with Fedora 7 (or later) and Red Hat Enterprise Linux version 5 (or later), it is possible, and, indeed, preferable, to specify the bonding options in the ifcfg-bond0 -file, e.g. a line of the format: +file, e.g. a line of the format:: -BONDING_OPTS="mode=active-backup arp_interval=60 arp_ip_target=192.168.1.254" + BONDING_OPTS="mode=active-backup arp_interval=60 arp_ip_target=192.168.1.254" - will configure the bond with the specified options. The options +will configure the bond with the specified options. The options specified in BONDING_OPTS are identical to the bonding module parameters except for the arp_ip_target field when using versions of initscripts older than and 8.57 (Fedora 8) and 8.45.19 (Red Hat Enterprise Linux 5.2). When using older versions each target should be included as a separate option and should be preceded by a '+' to indicate it should be added to the list of -queried targets, e.g., +queried targets, e.g.,:: - arp_ip_target=+192.168.1.1 arp_ip_target=+192.168.1.2 + arp_ip_target=+192.168.1.1 arp_ip_target=+192.168.1.2 - is the proper syntax to specify multiple targets. When specifying -options via BONDING_OPTS, it is not necessary to edit /etc/modprobe.d/*.conf. +is the proper syntax to specify multiple targets. When specifying +options via BONDING_OPTS, it is not necessary to edit +``/etc/modprobe.d/*.conf``. - For even older versions of initscripts that do not support +For even older versions of initscripts that do not support BONDING_OPTS, it is necessary to edit /etc/modprobe.d/*.conf, depending upon your distro) to load the bonding module with your desired options when the bond0 interface is brought up. The following lines in /etc/modprobe.d/*.conf will load the bonding module, and select its options: -alias bond0 bonding -options bond0 mode=balance-alb miimon=100 + alias bond0 bonding + options bond0 mode=balance-alb miimon=100 - Replace the sample parameters with the appropriate set of +Replace the sample parameters with the appropriate set of options for your configuration. - Finally run "/etc/rc.d/init.d/network restart" as root. This +Finally run "/etc/rc.d/init.d/network restart" as root. This will restart the networking subsystem and your bond link should be now up and running. 3.2.1 Using DHCP with Initscripts --------------------------------- - Recent versions of initscripts (the versions supplied with Fedora +Recent versions of initscripts (the versions supplied with Fedora Core 3 and Red Hat Enterprise Linux 4, or later versions, are reported to work) have support for assigning IP information to bonding devices via DHCP. - To configure bonding for DHCP, configure it as described +To configure bonding for DHCP, configure it as described above, except replace the line "BOOTPROTO=none" with "BOOTPROTO=dhcp" and add a line consisting of "TYPE=Bonding". Note that the TYPE value is case sensitive. @@ -1278,7 +1290,7 @@ is case sensitive. 3.2.2 Configuring Multiple Bonds with Initscripts ------------------------------------------------- - Initscripts packages that are included with Fedora 7 and Red Hat +Initscripts packages that are included with Fedora 7 and Red Hat Enterprise Linux 5 support multiple bonding interfaces by simply specifying the appropriate BONDING_OPTS= in ifcfg-bondX where X is the number of the bond. This support requires sysfs support in the kernel, @@ -1290,77 +1302,77 @@ below. 3.3 Configuring Bonding Manually with iproute2 ----------------------------------------------- - This section applies to distros whose network initialization +This section applies to distros whose network initialization scripts (the sysconfig or initscripts package) do not have specific knowledge of bonding. One such distro is SuSE Linux Enterprise Server version 8. - The general method for these systems is to place the bonding +The general method for these systems is to place the bonding module parameters into a config file in /etc/modprobe.d/ (as appropriate for the installed distro), then add modprobe and/or `ip link` commands to the system's global init script. The name of the global init script differs; for sysconfig, it is /etc/init.d/boot.local and for initscripts it is /etc/rc.d/rc.local. - For example, if you wanted to make a simple bond of two e100 +For example, if you wanted to make a simple bond of two e100 devices (presumed to be eth0 and eth1), and have it persist across reboots, edit the appropriate file (/etc/init.d/boot.local or -/etc/rc.d/rc.local), and add the following: +/etc/rc.d/rc.local), and add the following:: -modprobe bonding mode=balance-alb miimon=100 -modprobe e100 -ifconfig bond0 192.168.1.1 netmask 255.255.255.0 up -ip link set eth0 master bond0 -ip link set eth1 master bond0 + modprobe bonding mode=balance-alb miimon=100 + modprobe e100 + ifconfig bond0 192.168.1.1 netmask 255.255.255.0 up + ip link set eth0 master bond0 + ip link set eth1 master bond0 - Replace the example bonding module parameters and bond0 +Replace the example bonding module parameters and bond0 network configuration (IP address, netmask, etc) with the appropriate values for your configuration. - Unfortunately, this method will not provide support for the +Unfortunately, this method will not provide support for the ifup and ifdown scripts on the bond devices. To reload the bonding -configuration, it is necessary to run the initialization script, e.g., +configuration, it is necessary to run the initialization script, e.g.,:: -# /etc/init.d/boot.local + # /etc/init.d/boot.local - or +or:: -# /etc/rc.d/rc.local + # /etc/rc.d/rc.local - It may be desirable in such a case to create a separate script +It may be desirable in such a case to create a separate script which only initializes the bonding configuration, then call that separate script from within boot.local. This allows for bonding to be enabled without re-running the entire global init script. - To shut down the bonding devices, it is necessary to first +To shut down the bonding devices, it is necessary to first mark the bonding device itself as being down, then remove the appropriate device driver modules. For our example above, you can do -the following: +the following:: -# ifconfig bond0 down -# rmmod bonding -# rmmod e100 + # ifconfig bond0 down + # rmmod bonding + # rmmod e100 - Again, for convenience, it may be desirable to create a script +Again, for convenience, it may be desirable to create a script with these commands. 3.3.1 Configuring Multiple Bonds Manually ----------------------------------------- - This section contains information on configuring multiple +This section contains information on configuring multiple bonding devices with differing options for those systems whose network initialization scripts lack support for configuring multiple bonds. - If you require multiple bonding devices, but all with the same +If you require multiple bonding devices, but all with the same options, you may wish to use the "max_bonds" module parameter, documented above. - To create multiple bonding devices with differing options, it is +To create multiple bonding devices with differing options, it is preferable to use bonding parameters exported by sysfs, documented in the section below. - For versions of bonding without sysfs support, the only means to +For versions of bonding without sysfs support, the only means to provide multiple instances of bonding with differing options is to load the bonding driver multiple times. Note that current versions of the sysconfig network initialization scripts handle this automatically; if @@ -1368,35 +1380,35 @@ your distro uses these scripts, no special action is needed. See the section Configuring Bonding Devices, above, if you're not sure about your network initialization scripts. - To load multiple instances of the module, it is necessary to +To load multiple instances of the module, it is necessary to specify a different name for each instance (the module loading system requires that every loaded module, even multiple instances of the same module, have a unique name). This is accomplished by supplying multiple -sets of bonding options in /etc/modprobe.d/*.conf, for example: +sets of bonding options in ``/etc/modprobe.d/*.conf``, for example:: -alias bond0 bonding -options bond0 -o bond0 mode=balance-rr miimon=100 + alias bond0 bonding + options bond0 -o bond0 mode=balance-rr miimon=100 -alias bond1 bonding -options bond1 -o bond1 mode=balance-alb miimon=50 + alias bond1 bonding + options bond1 -o bond1 mode=balance-alb miimon=50 - will load the bonding module two times. The first instance is +will load the bonding module two times. The first instance is named "bond0" and creates the bond0 device in balance-rr mode with an miimon of 100. The second instance is named "bond1" and creates the bond1 device in balance-alb mode with an miimon of 50. - In some circumstances (typically with older distributions), +In some circumstances (typically with older distributions), the above does not work, and the second bonding instance never sees its options. In that case, the second options line can be substituted -as follows: +as follows:: -install bond1 /sbin/modprobe --ignore-install bonding -o bond1 \ - mode=balance-alb miimon=50 + install bond1 /sbin/modprobe --ignore-install bonding -o bond1 \ + mode=balance-alb miimon=50 - This may be repeated any number of times, specifying a new and +This may be repeated any number of times, specifying a new and unique name in place of bond1 for each subsequent instance. - It has been observed that some Red Hat supplied kernels are unable +It has been observed that some Red Hat supplied kernels are unable to rename modules at load time (the "-o bond1" part). Attempts to pass that option to modprobe will produce an "Operation not permitted" error. This has been reported on some Fedora Core kernels, and has been seen on @@ -1407,18 +1419,18 @@ kernels, and also lack sysfs support). 3.4 Configuring Bonding Manually via Sysfs ------------------------------------------ - Starting with version 3.0.0, Channel Bonding may be configured +Starting with version 3.0.0, Channel Bonding may be configured via the sysfs interface. This interface allows dynamic configuration of all bonds in the system without unloading the module. It also allows for adding and removing bonds at runtime. Ifenslave is no longer required, though it is still supported. - Use of the sysfs interface allows you to use multiple bonds +Use of the sysfs interface allows you to use multiple bonds with different configurations without having to reload the module. It also allows you to use multiple, differently configured bonds when bonding is compiled into the kernel. - You must have the sysfs filesystem mounted to configure +You must have the sysfs filesystem mounted to configure bonding this way. The examples in this document assume that you are using the standard mount point for sysfs, e.g. /sys. If your sysfs filesystem is mounted elsewhere, you will need to adjust the @@ -1426,38 +1438,45 @@ example paths accordingly. Creating and Destroying Bonds ----------------------------- -To add a new bond foo: -# echo +foo > /sys/class/net/bonding_masters +To add a new bond foo:: -To remove an existing bond bar: -# echo -bar > /sys/class/net/bonding_masters + # echo +foo > /sys/class/net/bonding_masters -To show all existing bonds: -# cat /sys/class/net/bonding_masters +To remove an existing bond bar:: -NOTE: due to 4K size limitation of sysfs files, this list may be -truncated if you have more than a few hundred bonds. This is unlikely -to occur under normal operating conditions. + # echo -bar > /sys/class/net/bonding_masters + +To show all existing bonds:: + + # cat /sys/class/net/bonding_masters + +.. note:: + + due to 4K size limitation of sysfs files, this list may be + truncated if you have more than a few hundred bonds. This is unlikely + to occur under normal operating conditions. Adding and Removing Slaves -------------------------- - Interfaces may be enslaved to a bond using the file +Interfaces may be enslaved to a bond using the file /sys/class/net//bonding/slaves. The semantics for this file are the same as for the bonding_masters file. -To enslave interface eth0 to bond bond0: -# ifconfig bond0 up -# echo +eth0 > /sys/class/net/bond0/bonding/slaves +To enslave interface eth0 to bond bond0:: -To free slave eth0 from bond bond0: -# echo -eth0 > /sys/class/net/bond0/bonding/slaves + # ifconfig bond0 up + # echo +eth0 > /sys/class/net/bond0/bonding/slaves - When an interface is enslaved to a bond, symlinks between the +To free slave eth0 from bond bond0:: + + # echo -eth0 > /sys/class/net/bond0/bonding/slaves + +When an interface is enslaved to a bond, symlinks between the two are created in the sysfs filesystem. In this case, you would get /sys/class/net/bond0/slave_eth0 pointing to /sys/class/net/eth0, and /sys/class/net/eth0/master pointing to /sys/class/net/bond0. - This means that you can tell quickly whether or not an +This means that you can tell quickly whether or not an interface is enslaved by looking for the master symlink. Thus: # echo -eth0 > /sys/class/net/eth0/master/bonding/slaves will free eth0 from whatever bond it is enslaved to, regardless of @@ -1465,127 +1484,143 @@ the name of the bond interface. Changing a Bond's Configuration ------------------------------- - Each bond may be configured individually by manipulating the +Each bond may be configured individually by manipulating the files located in /sys/class/net//bonding - The names of these files correspond directly with the command- +The names of these files correspond directly with the command- line parameters described elsewhere in this file, and, with the exception of arp_ip_target, they accept the same values. To see the current setting, simply cat the appropriate file. - A few examples will be given here; for specific usage +A few examples will be given here; for specific usage guidelines for each parameter, see the appropriate section in this document. -To configure bond0 for balance-alb mode: -# ifconfig bond0 down -# echo 6 > /sys/class/net/bond0/bonding/mode - - or - -# echo balance-alb > /sys/class/net/bond0/bonding/mode - NOTE: The bond interface must be down before the mode can be -changed. - -To enable MII monitoring on bond0 with a 1 second interval: -# echo 1000 > /sys/class/net/bond0/bonding/miimon - NOTE: If ARP monitoring is enabled, it will disabled when MII -monitoring is enabled, and vice-versa. - -To add ARP targets: -# echo +192.168.0.100 > /sys/class/net/bond0/bonding/arp_ip_target -# echo +192.168.0.101 > /sys/class/net/bond0/bonding/arp_ip_target - NOTE: up to 16 target addresses may be specified. - -To remove an ARP target: -# echo -192.168.0.100 > /sys/class/net/bond0/bonding/arp_ip_target - -To configure the interval between learning packet transmits: -# echo 12 > /sys/class/net/bond0/bonding/lp_interval - NOTE: the lp_interval is the number of seconds between instances where -the bonding driver sends learning packets to each slaves peer switch. The -default interval is 1 second. +To configure bond0 for balance-alb mode:: + + # ifconfig bond0 down + # echo 6 > /sys/class/net/bond0/bonding/mode + - or - + # echo balance-alb > /sys/class/net/bond0/bonding/mode + +.. note:: + + The bond interface must be down before the mode can be changed. + +To enable MII monitoring on bond0 with a 1 second interval:: + + # echo 1000 > /sys/class/net/bond0/bonding/miimon + +.. note:: + + If ARP monitoring is enabled, it will disabled when MII + monitoring is enabled, and vice-versa. + +To add ARP targets:: + + # echo +192.168.0.100 > /sys/class/net/bond0/bonding/arp_ip_target + # echo +192.168.0.101 > /sys/class/net/bond0/bonding/arp_ip_target + +.. note:: + + up to 16 target addresses may be specified. + +To remove an ARP target:: + + # echo -192.168.0.100 > /sys/class/net/bond0/bonding/arp_ip_target + +To configure the interval between learning packet transmits:: + + # echo 12 > /sys/class/net/bond0/bonding/lp_interval + +.. note:: + + the lp_interval is the number of seconds between instances where + the bonding driver sends learning packets to each slaves peer switch. The + default interval is 1 second. Example Configuration --------------------- - We begin with the same example that is shown in section 3.3, +We begin with the same example that is shown in section 3.3, executed with sysfs, and without using ifenslave. - To make a simple bond of two e100 devices (presumed to be eth0 +To make a simple bond of two e100 devices (presumed to be eth0 and eth1), and have it persist across reboots, edit the appropriate file (/etc/init.d/boot.local or /etc/rc.d/rc.local), and add the -following: +following:: -modprobe bonding -modprobe e100 -echo balance-alb > /sys/class/net/bond0/bonding/mode -ifconfig bond0 192.168.1.1 netmask 255.255.255.0 up -echo 100 > /sys/class/net/bond0/bonding/miimon -echo +eth0 > /sys/class/net/bond0/bonding/slaves -echo +eth1 > /sys/class/net/bond0/bonding/slaves + modprobe bonding + modprobe e100 + echo balance-alb > /sys/class/net/bond0/bonding/mode + ifconfig bond0 192.168.1.1 netmask 255.255.255.0 up + echo 100 > /sys/class/net/bond0/bonding/miimon + echo +eth0 > /sys/class/net/bond0/bonding/slaves + echo +eth1 > /sys/class/net/bond0/bonding/slaves - To add a second bond, with two e1000 interfaces in +To add a second bond, with two e1000 interfaces in active-backup mode, using ARP monitoring, add the following lines to -your init script: +your init script:: -modprobe e1000 -echo +bond1 > /sys/class/net/bonding_masters -echo active-backup > /sys/class/net/bond1/bonding/mode -ifconfig bond1 192.168.2.1 netmask 255.255.255.0 up -echo +192.168.2.100 /sys/class/net/bond1/bonding/arp_ip_target -echo 2000 > /sys/class/net/bond1/bonding/arp_interval -echo +eth2 > /sys/class/net/bond1/bonding/slaves -echo +eth3 > /sys/class/net/bond1/bonding/slaves + modprobe e1000 + echo +bond1 > /sys/class/net/bonding_masters + echo active-backup > /sys/class/net/bond1/bonding/mode + ifconfig bond1 192.168.2.1 netmask 255.255.255.0 up + echo +192.168.2.100 /sys/class/net/bond1/bonding/arp_ip_target + echo 2000 > /sys/class/net/bond1/bonding/arp_interval + echo +eth2 > /sys/class/net/bond1/bonding/slaves + echo +eth3 > /sys/class/net/bond1/bonding/slaves 3.5 Configuration with Interfaces Support ----------------------------------------- - This section applies to distros which use /etc/network/interfaces file +This section applies to distros which use /etc/network/interfaces file to describe network interface configuration, most notably Debian and it's derivatives. - The ifup and ifdown commands on Debian don't support bonding out of +The ifup and ifdown commands on Debian don't support bonding out of the box. The ifenslave-2.6 package should be installed to provide bonding -support. Once installed, this package will provide bond-* options to be used -into /etc/network/interfaces. +support. Once installed, this package will provide ``bond-*`` options +to be used into /etc/network/interfaces. - Note that ifenslave-2.6 package will load the bonding module and use +Note that ifenslave-2.6 package will load the bonding module and use the ifenslave command when appropriate. Example Configurations ---------------------- In /etc/network/interfaces, the following stanza will configure bond0, in -active-backup mode, with eth0 and eth1 as slaves. +active-backup mode, with eth0 and eth1 as slaves:: -auto bond0 -iface bond0 inet dhcp - bond-slaves eth0 eth1 - bond-mode active-backup - bond-miimon 100 - bond-primary eth0 eth1 + auto bond0 + iface bond0 inet dhcp + bond-slaves eth0 eth1 + bond-mode active-backup + bond-miimon 100 + bond-primary eth0 eth1 If the above configuration doesn't work, you might have a system using upstart for system startup. This is most notably true for recent Ubuntu versions. The following stanza in /etc/network/interfaces will -produce the same result on those systems. +produce the same result on those systems:: -auto bond0 -iface bond0 inet dhcp - bond-slaves none - bond-mode active-backup - bond-miimon 100 + auto bond0 + iface bond0 inet dhcp + bond-slaves none + bond-mode active-backup + bond-miimon 100 -auto eth0 -iface eth0 inet manual - bond-master bond0 - bond-primary eth0 eth1 + auto eth0 + iface eth0 inet manual + bond-master bond0 + bond-primary eth0 eth1 -auto eth1 -iface eth1 inet manual - bond-master bond0 - bond-primary eth0 eth1 + auto eth1 + iface eth1 inet manual + bond-master bond0 + bond-primary eth0 eth1 -For a full list of bond-* supported options in /etc/network/interfaces and some -more advanced examples tailored to you particular distros, see the files in +For a full list of ``bond-*`` supported options in /etc/network/interfaces and +some more advanced examples tailored to you particular distros, see the files in /usr/share/doc/ifenslave-2.6. 3.6 Overriding Configuration for Special Cases @@ -1610,31 +1645,31 @@ tx_queues can be used to change this value. There is no sysfs parameter available as the allocation is done at module init time. The output of the file /proc/net/bonding/bondX has changed so the output Queue -ID is now printed for each slave: +ID is now printed for each slave:: -Bonding Mode: fault-tolerance (active-backup) -Primary Slave: None -Currently Active Slave: eth0 -MII Status: up -MII Polling Interval (ms): 0 -Up Delay (ms): 0 -Down Delay (ms): 0 + Bonding Mode: fault-tolerance (active-backup) + Primary Slave: None + Currently Active Slave: eth0 + MII Status: up + MII Polling Interval (ms): 0 + Up Delay (ms): 0 + Down Delay (ms): 0 -Slave Interface: eth0 -MII Status: up -Link Failure Count: 0 -Permanent HW addr: 00:1a:a0:12:8f:cb -Slave queue ID: 0 + Slave Interface: eth0 + MII Status: up + Link Failure Count: 0 + Permanent HW addr: 00:1a:a0:12:8f:cb + Slave queue ID: 0 -Slave Interface: eth1 -MII Status: up -Link Failure Count: 0 -Permanent HW addr: 00:1a:a0:12:8f:cc -Slave queue ID: 2 + Slave Interface: eth1 + MII Status: up + Link Failure Count: 0 + Permanent HW addr: 00:1a:a0:12:8f:cc + Slave queue ID: 2 -The queue_id for a slave can be set using the command: +The queue_id for a slave can be set using the command:: -# echo "eth1:2" > /sys/class/net/bond0/bonding/queue_id + # echo "eth1:2" > /sys/class/net/bond0/bonding/queue_id Any interface that needs a queue_id set should set it with multiple calls like the one above until proper priorities are set for all interfaces. On @@ -1645,12 +1680,12 @@ These queue id's can be used in conjunction with the tc utility to configure a multiqueue qdisc and filters to bias certain traffic to transmit on certain slave devices. For instance, say we wanted, in the above configuration to force all traffic bound to 192.168.1.100 to use eth1 in the bond as its output -device. The following commands would accomplish this: +device. The following commands would accomplish this:: -# tc qdisc add dev bond0 handle 1 root multiq + # tc qdisc add dev bond0 handle 1 root multiq -# tc filter add dev bond0 protocol ip parent 1: prio 1 u32 match ip dst \ - 192.168.1.100 action skbedit queue_mapping 2 + # tc filter add dev bond0 protocol ip parent 1: prio 1 u32 match ip \ + dst 192.168.1.100 action skbedit queue_mapping 2 These commands tell the kernel to attach a multiqueue queue discipline to the bond0 interface and filter traffic enqueued to it, such that packets with a dst @@ -1663,7 +1698,7 @@ that normal output policy selection should take place. One benefit to simply leaving the qid for a slave to 0 is the multiqueue awareness in the bonding driver that is now present. This awareness allows tc filters to be placed on slave devices as well as bond devices and the bonding driver will simply act as -a pass-through for selecting output queues on the slave device rather than +a pass-through for selecting output queues on the slave device rather than output port selection. This feature first appeared in bonding driver version 3.7.0 and support for @@ -1689,31 +1724,31 @@ few bonding parameters: (a) ad_actor_system : You can set a random mac-address that can be used for these LACPDU exchanges. The value can not be either NULL or Multicast. Also it's preferable to set the local-admin bit. Following shell code - generates a random mac-address as described above. + generates a random mac-address as described above:: - # sys_mac_addr=$(printf '%02x:%02x:%02x:%02x:%02x:%02x' \ - $(( (RANDOM & 0xFE) | 0x02 )) \ - $(( RANDOM & 0xFF )) \ - $(( RANDOM & 0xFF )) \ - $(( RANDOM & 0xFF )) \ - $(( RANDOM & 0xFF )) \ - $(( RANDOM & 0xFF ))) - # echo $sys_mac_addr > /sys/class/net/bond0/bonding/ad_actor_system + # sys_mac_addr=$(printf '%02x:%02x:%02x:%02x:%02x:%02x' \ + $(( (RANDOM & 0xFE) | 0x02 )) \ + $(( RANDOM & 0xFF )) \ + $(( RANDOM & 0xFF )) \ + $(( RANDOM & 0xFF )) \ + $(( RANDOM & 0xFF )) \ + $(( RANDOM & 0xFF ))) + # echo $sys_mac_addr > /sys/class/net/bond0/bonding/ad_actor_system (b) ad_actor_sys_prio : Randomize the system priority. The default value is 65535, but system can take the value from 1 - 65535. Following shell - code generates random priority and sets it. + code generates random priority and sets it:: - # sys_prio=$(( 1 + RANDOM + RANDOM )) - # echo $sys_prio > /sys/class/net/bond0/bonding/ad_actor_sys_prio + # sys_prio=$(( 1 + RANDOM + RANDOM )) + # echo $sys_prio > /sys/class/net/bond0/bonding/ad_actor_sys_prio (c) ad_user_port_key : Use the user portion of the port-key. The default keeps this empty. These are the upper 10 bits of the port-key and value ranges from 0 - 1023. Following shell code generates these 10 bits and - sets it. + sets it:: - # usr_port_key=$(( RANDOM & 0x3FF )) - # echo $usr_port_key > /sys/class/net/bond0/bonding/ad_user_port_key + # usr_port_key=$(( RANDOM & 0x3FF )) + # echo $usr_port_key > /sys/class/net/bond0/bonding/ad_user_port_key 4 Querying Bonding Configuration @@ -1722,81 +1757,81 @@ few bonding parameters: 4.1 Bonding Configuration ------------------------- - Each bonding device has a read-only file residing in the +Each bonding device has a read-only file residing in the /proc/net/bonding directory. The file contents include information about the bonding configuration, options and state of each slave. - For example, the contents of /proc/net/bonding/bond0 after the +For example, the contents of /proc/net/bonding/bond0 after the driver is loaded with parameters of mode=0 and miimon=1000 is -generally as follows: +generally as follows:: Ethernet Channel Bonding Driver: 2.6.1 (October 29, 2004) - Bonding Mode: load balancing (round-robin) - Currently Active Slave: eth0 - MII Status: up - MII Polling Interval (ms): 1000 - Up Delay (ms): 0 - Down Delay (ms): 0 + Bonding Mode: load balancing (round-robin) + Currently Active Slave: eth0 + MII Status: up + MII Polling Interval (ms): 1000 + Up Delay (ms): 0 + Down Delay (ms): 0 - Slave Interface: eth1 - MII Status: up - Link Failure Count: 1 + Slave Interface: eth1 + MII Status: up + Link Failure Count: 1 - Slave Interface: eth0 - MII Status: up - Link Failure Count: 1 + Slave Interface: eth0 + MII Status: up + Link Failure Count: 1 - The precise format and contents will change depending upon the +The precise format and contents will change depending upon the bonding configuration, state, and version of the bonding driver. 4.2 Network configuration ------------------------- - The network configuration can be inspected using the ifconfig +The network configuration can be inspected using the ifconfig command. Bonding devices will have the MASTER flag set; Bonding slave devices will have the SLAVE flag set. The ifconfig output does not contain information on which slaves are associated with which masters. - In the example below, the bond0 interface is the master +In the example below, the bond0 interface is the master (MASTER) while eth0 and eth1 are slaves (SLAVE). Notice all slaves of bond0 have the same MAC address (HWaddr) as bond0 for all modes except -TLB and ALB that require a unique MAC address for each slave. +TLB and ALB that require a unique MAC address for each slave:: -# /sbin/ifconfig -bond0 Link encap:Ethernet HWaddr 00:C0:F0:1F:37:B4 - inet addr:XXX.XXX.XXX.YYY Bcast:XXX.XXX.XXX.255 Mask:255.255.252.0 - UP BROADCAST RUNNING MASTER MULTICAST MTU:1500 Metric:1 - RX packets:7224794 errors:0 dropped:0 overruns:0 frame:0 - TX packets:3286647 errors:1 dropped:0 overruns:1 carrier:0 - collisions:0 txqueuelen:0 + # /sbin/ifconfig + bond0 Link encap:Ethernet HWaddr 00:C0:F0:1F:37:B4 + inet addr:XXX.XXX.XXX.YYY Bcast:XXX.XXX.XXX.255 Mask:255.255.252.0 + UP BROADCAST RUNNING MASTER MULTICAST MTU:1500 Metric:1 + RX packets:7224794 errors:0 dropped:0 overruns:0 frame:0 + TX packets:3286647 errors:1 dropped:0 overruns:1 carrier:0 + collisions:0 txqueuelen:0 -eth0 Link encap:Ethernet HWaddr 00:C0:F0:1F:37:B4 - UP BROADCAST RUNNING SLAVE MULTICAST MTU:1500 Metric:1 - RX packets:3573025 errors:0 dropped:0 overruns:0 frame:0 - TX packets:1643167 errors:1 dropped:0 overruns:1 carrier:0 - collisions:0 txqueuelen:100 - Interrupt:10 Base address:0x1080 + eth0 Link encap:Ethernet HWaddr 00:C0:F0:1F:37:B4 + UP BROADCAST RUNNING SLAVE MULTICAST MTU:1500 Metric:1 + RX packets:3573025 errors:0 dropped:0 overruns:0 frame:0 + TX packets:1643167 errors:1 dropped:0 overruns:1 carrier:0 + collisions:0 txqueuelen:100 + Interrupt:10 Base address:0x1080 -eth1 Link encap:Ethernet HWaddr 00:C0:F0:1F:37:B4 - UP BROADCAST RUNNING SLAVE MULTICAST MTU:1500 Metric:1 - RX packets:3651769 errors:0 dropped:0 overruns:0 frame:0 - TX packets:1643480 errors:0 dropped:0 overruns:0 carrier:0 - collisions:0 txqueuelen:100 - Interrupt:9 Base address:0x1400 + eth1 Link encap:Ethernet HWaddr 00:C0:F0:1F:37:B4 + UP BROADCAST RUNNING SLAVE MULTICAST MTU:1500 Metric:1 + RX packets:3651769 errors:0 dropped:0 overruns:0 frame:0 + TX packets:1643480 errors:0 dropped:0 overruns:0 carrier:0 + collisions:0 txqueuelen:100 + Interrupt:9 Base address:0x1400 5. Switch Configuration ======================= - For this section, "switch" refers to whatever system the +For this section, "switch" refers to whatever system the bonded devices are directly connected to (i.e., where the other end of the cable plugs into). This may be an actual dedicated switch device, or it may be another regular system (e.g., another computer running Linux), - The active-backup, balance-tlb and balance-alb modes do not +The active-backup, balance-tlb and balance-alb modes do not require any specific configuration of the switch. - The 802.3ad mode requires that the switch have the appropriate +The 802.3ad mode requires that the switch have the appropriate ports configured as an 802.3ad aggregation. The precise method used to configure this varies from switch to switch, but, for example, a Cisco 3550 series switch requires that the appropriate ports first be @@ -1804,7 +1839,7 @@ grouped together in a single etherchannel instance, then that etherchannel is set to mode "lacp" to enable 802.3ad (instead of standard EtherChannel). - The balance-rr, balance-xor and broadcast modes generally +The balance-rr, balance-xor and broadcast modes generally require that the switch have the appropriate ports grouped together. The nomenclature for such a group differs between switches, it may be called an "etherchannel" (as in the Cisco example, above), a "trunk @@ -1820,7 +1855,7 @@ with another EtherChannel group. 6. 802.1q VLAN Support ====================== - It is possible to configure VLAN devices over a bond interface +It is possible to configure VLAN devices over a bond interface using the 8021q driver. However, only packets coming from the 8021q driver and passing through bonding will be tagged by default. Self generated packets, for example, bonding's learning packets or ARP @@ -1829,7 +1864,7 @@ tagged internally by bonding itself. As a result, bonding must "learn" the VLAN IDs configured above it, and use those IDs to tag self generated packets. - For reasons of simplicity, and to support the use of adapters +For reasons of simplicity, and to support the use of adapters that can do VLAN hardware acceleration offloading, the bonding interface declares itself as fully hardware offloading capable, it gets the add_vid/kill_vid notifications to gather the necessary @@ -1839,7 +1874,7 @@ should go through an adapter that is not offloading capable are "un-accelerated" by the bonding driver so the VLAN tag sits in the regular location. - VLAN interfaces *must* be added on top of a bonding interface +VLAN interfaces *must* be added on top of a bonding interface only after enslaving at least one slave. The bonding interface has a hardware address of 00:00:00:00:00:00 until the first slave is added. If the VLAN interface is created prior to the first enslavement, it @@ -1847,23 +1882,23 @@ would pick up the all-zeroes hardware address. Once the first slave is attached to the bond, the bond device itself will pick up the slave's hardware address, which is then available for the VLAN device. - Also, be aware that a similar problem can occur if all slaves +Also, be aware that a similar problem can occur if all slaves are released from a bond that still has one or more VLAN interfaces on top of it. When a new slave is added, the bonding interface will obtain its hardware address from the first slave, which might not match the hardware address of the VLAN interfaces (which was ultimately copied from an earlier slave). - There are two methods to insure that the VLAN device operates +There are two methods to insure that the VLAN device operates with the correct hardware address if all slaves are removed from a bond interface: - 1. Remove all VLAN interfaces then recreate them +1. Remove all VLAN interfaces then recreate them - 2. Set the bonding interface's hardware address so that it +2. Set the bonding interface's hardware address so that it matches the hardware address of the VLAN interfaces. - Note that changing a VLAN interface's HW address would set the +Note that changing a VLAN interface's HW address would set the underlying device -- i.e. the bonding interface -- to promiscuous mode, which might not be what you want. @@ -1871,24 +1906,24 @@ mode, which might not be what you want. 7. Link Monitoring ================== - The bonding driver at present supports two schemes for +The bonding driver at present supports two schemes for monitoring a slave device's link state: the ARP monitor and the MII monitor. - At the present time, due to implementation restrictions in the +At the present time, due to implementation restrictions in the bonding driver itself, it is not possible to enable both ARP and MII monitoring simultaneously. 7.1 ARP Monitor Operation ------------------------- - The ARP monitor operates as its name suggests: it sends ARP +The ARP monitor operates as its name suggests: it sends ARP queries to one or more designated peer systems on the network, and uses the response as an indication that the link is operating. This gives some assurance that traffic is actually flowing to and from one or more peers on the local network. - The ARP monitor relies on the device driver itself to verify +The ARP monitor relies on the device driver itself to verify that traffic is flowing. In particular, the driver must keep up to date the last receive time, dev->last_rx. Drivers that use NETIF_F_LLTX flag must also update netdev_queue->trans_start. If they do not, then the @@ -1900,36 +1935,36 @@ your device driver is not updating last_rx and trans_start. 7.2 Configuring Multiple ARP Targets ------------------------------------ - While ARP monitoring can be done with just one target, it can +While ARP monitoring can be done with just one target, it can be useful in a High Availability setup to have several targets to monitor. In the case of just one target, the target itself may go down or have a problem making it unresponsive to ARP requests. Having an additional target (or several) increases the reliability of the ARP monitoring. - Multiple ARP targets must be separated by commas as follows: +Multiple ARP targets must be separated by commas as follows:: -# example options for ARP monitoring with three targets -alias bond0 bonding -options bond0 arp_interval=60 arp_ip_target=192.168.0.1,192.168.0.3,192.168.0.9 + # example options for ARP monitoring with three targets + alias bond0 bonding + options bond0 arp_interval=60 arp_ip_target=192.168.0.1,192.168.0.3,192.168.0.9 - For just a single target the options would resemble: +For just a single target the options would resemble:: -# example options for ARP monitoring with one target -alias bond0 bonding -options bond0 arp_interval=60 arp_ip_target=192.168.0.100 + # example options for ARP monitoring with one target + alias bond0 bonding + options bond0 arp_interval=60 arp_ip_target=192.168.0.100 7.3 MII Monitor Operation ------------------------- - The MII monitor monitors only the carrier state of the local +The MII monitor monitors only the carrier state of the local network interface. It accomplishes this in one of three ways: by depending upon the device driver to maintain its carrier state, by querying the device's MII registers, or by making an ethtool query to the device. - If the use_carrier module parameter is 1 (the default value), +If the use_carrier module parameter is 1 (the default value), then the MII monitor will rely on the driver for carrier state information (via the netif_carrier subsystem). As explained in the use_carrier parameter information, above, if the MII monitor fails to @@ -1937,7 +1972,7 @@ detect carrier loss on the device (e.g., when the cable is physically disconnected), it may be that the driver does not support netif_carrier. - If use_carrier is 0, then the MII monitor will first query the +If use_carrier is 0, then the MII monitor will first query the device's (via ioctl) MII registers and check the link state. If that request fails (not just that it returns carrier down), then the MII monitor will make an ethtool ETHOOL_GLINK request to attempt to obtain @@ -1952,25 +1987,25 @@ up. 8.1 Adventures in Routing ------------------------- - When bonding is configured, it is important that the slave +When bonding is configured, it is important that the slave devices not have routes that supersede routes of the master (or, generally, not have routes at all). For example, suppose the bonding device bond0 has two slaves, eth0 and eth1, and the routing table is -as follows: +as follows:: -Kernel IP routing table -Destination Gateway Genmask Flags MSS Window irtt Iface -10.0.0.0 0.0.0.0 255.255.0.0 U 40 0 0 eth0 -10.0.0.0 0.0.0.0 255.255.0.0 U 40 0 0 eth1 -10.0.0.0 0.0.0.0 255.255.0.0 U 40 0 0 bond0 -127.0.0.0 0.0.0.0 255.0.0.0 U 40 0 0 lo + Kernel IP routing table + Destination Gateway Genmask Flags MSS Window irtt Iface + 10.0.0.0 0.0.0.0 255.255.0.0 U 40 0 0 eth0 + 10.0.0.0 0.0.0.0 255.255.0.0 U 40 0 0 eth1 + 10.0.0.0 0.0.0.0 255.255.0.0 U 40 0 0 bond0 + 127.0.0.0 0.0.0.0 255.0.0.0 U 40 0 0 lo - This routing configuration will likely still update the +This routing configuration will likely still update the receive/transmit times in the driver (needed by the ARP monitor), but may bypass the bonding driver (because outgoing traffic to, in this case, another host on network 10 would use eth0 or eth1 before bond0). - The ARP monitor (and ARP itself) may become confused by this +The ARP monitor (and ARP itself) may become confused by this configuration, because ARP requests (generated by the ARP monitor) will be sent on one interface (bond0), but the corresponding reply will arrive on a different interface (eth0). This reply looks to ARP @@ -1978,7 +2013,7 @@ as an unsolicited ARP reply (because ARP matches replies on an interface basis), and is discarded. The MII monitor is not affected by the state of the routing table. - The solution here is simply to insure that slaves do not have +The solution here is simply to insure that slaves do not have routes of their own, and if for some reason they must, those routes do not supersede routes of their master. This should generally be the case, but unusual configurations or errant manual or automatic static @@ -1987,22 +2022,22 @@ route additions may cause trouble. 8.2 Ethernet Device Renaming ---------------------------- - On systems with network configuration scripts that do not +On systems with network configuration scripts that do not associate physical devices directly with network interface names (so that the same physical device always has the same "ethX" name), it may be necessary to add some special logic to config files in /etc/modprobe.d/. - For example, given a modules.conf containing the following: +For example, given a modules.conf containing the following:: -alias bond0 bonding -options bond0 mode=some-mode miimon=50 -alias eth0 tg3 -alias eth1 tg3 -alias eth2 e1000 -alias eth3 e1000 + alias bond0 bonding + options bond0 mode=some-mode miimon=50 + alias eth0 tg3 + alias eth1 tg3 + alias eth2 e1000 + alias eth3 e1000 - If neither eth0 and eth1 are slaves to bond0, then when the +If neither eth0 and eth1 are slaves to bond0, then when the bond0 interface comes up, the devices may end up reordered. This happens because bonding is loaded first, then its slave device's drivers are loaded next. Since no other drivers have been loaded, @@ -2010,36 +2045,36 @@ when the e1000 driver loads, it will receive eth0 and eth1 for its devices, but the bonding configuration tries to enslave eth2 and eth3 (which may later be assigned to the tg3 devices). - Adding the following: +Adding the following:: -add above bonding e1000 tg3 + add above bonding e1000 tg3 - causes modprobe to load e1000 then tg3, in that order, when +causes modprobe to load e1000 then tg3, in that order, when bonding is loaded. This command is fully documented in the modules.conf manual page. - On systems utilizing modprobe an equivalent problem can occur. +On systems utilizing modprobe an equivalent problem can occur. In this case, the following can be added to config files in -/etc/modprobe.d/ as: +/etc/modprobe.d/ as:: -softdep bonding pre: tg3 e1000 + softdep bonding pre: tg3 e1000 - This will load tg3 and e1000 modules before loading the bonding one. +This will load tg3 and e1000 modules before loading the bonding one. Full documentation on this can be found in the modprobe.d and modprobe manual pages. 8.3. Painfully Slow Or No Failed Link Detection By Miimon --------------------------------------------------------- - By default, bonding enables the use_carrier option, which +By default, bonding enables the use_carrier option, which instructs bonding to trust the driver to maintain carrier state. - As discussed in the options section, above, some drivers do +As discussed in the options section, above, some drivers do not support the netif_carrier_on/_off link state tracking system. With use_carrier enabled, bonding will always see these links as up, regardless of their actual state. - Additionally, other drivers do support netif_carrier, but do +Additionally, other drivers do support netif_carrier, but do not maintain it in real time, e.g., only polling the link state at some fixed interval. In this case, miimon will detect failures, but only after some long period of time has expired. If it appears that @@ -2051,7 +2086,7 @@ use_carrier=0 method of querying the registers directly works). If use_carrier=0 does not improve the failover, then the driver may cache the registers, or the problem may be elsewhere. - Also, remember that miimon only checks for the device's +Also, remember that miimon only checks for the device's carrier state. It has no way to determine the state of devices on or beyond other ports of a switch, or if a switch is refusing to pass traffic while still maintaining carrier on. @@ -2059,7 +2094,7 @@ traffic while still maintaining carrier on. 9. SNMP agents =============== - If running SNMP agents, the bonding driver should be loaded +If running SNMP agents, the bonding driver should be loaded before any network drivers participating in a bond. This requirement is due to the interface index (ipAdEntIfIndex) being associated to the first interface found with a given IP address. That is, there is @@ -2070,6 +2105,8 @@ with the eth0 interface. This configuration is shown below, the IP address 192.168.1.1 has an interface index of 2 which indexes to eth0 in the ifDescr table (ifDescr.2). +:: + interfaces.ifTable.ifEntry.ifDescr.1 = lo interfaces.ifTable.ifEntry.ifDescr.2 = eth0 interfaces.ifTable.ifEntry.ifDescr.3 = eth1 @@ -2081,7 +2118,7 @@ in the ifDescr table (ifDescr.2). ip.ipAddrTable.ipAddrEntry.ipAdEntIfIndex.10.74.20.94 = 4 ip.ipAddrTable.ipAddrEntry.ipAdEntIfIndex.127.0.0.1 = 1 - This problem is avoided by loading the bonding driver before +This problem is avoided by loading the bonding driver before any network drivers participating in a bond. Below is an example of loading the bonding driver first, the IP address 192.168.1.1 is correctly associated with ifDescr.2. @@ -2097,7 +2134,7 @@ correctly associated with ifDescr.2. ip.ipAddrTable.ipAddrEntry.ipAdEntIfIndex.10.74.20.94 = 5 ip.ipAddrTable.ipAddrEntry.ipAdEntIfIndex.127.0.0.1 = 1 - While some distributions may not report the interface name in +While some distributions may not report the interface name in ifDescr, the association between the IP address and IfIndex remains and SNMP functions such as Interface_Scan_Next will report that association. @@ -2105,34 +2142,34 @@ association. 10. Promiscuous mode ==================== - When running network monitoring tools, e.g., tcpdump, it is +When running network monitoring tools, e.g., tcpdump, it is common to enable promiscuous mode on the device, so that all traffic is seen (instead of seeing only traffic destined for the local host). The bonding driver handles promiscuous mode changes to the bonding master device (e.g., bond0), and propagates the setting to the slave devices. - For the balance-rr, balance-xor, broadcast, and 802.3ad modes, +For the balance-rr, balance-xor, broadcast, and 802.3ad modes, the promiscuous mode setting is propagated to all slaves. - For the active-backup, balance-tlb and balance-alb modes, the +For the active-backup, balance-tlb and balance-alb modes, the promiscuous mode setting is propagated only to the active slave. - For balance-tlb mode, the active slave is the slave currently +For balance-tlb mode, the active slave is the slave currently receiving inbound traffic. - For balance-alb mode, the active slave is the slave used as a +For balance-alb mode, the active slave is the slave used as a "primary." This slave is used for mode-specific control traffic, for sending to peers that are unassigned or if the load is unbalanced. - For the active-backup, balance-tlb and balance-alb modes, when +For the active-backup, balance-tlb and balance-alb modes, when the active slave changes (e.g., due to a link failure), the promiscuous setting will be propagated to the new active slave. 11. Configuring Bonding for High Availability ============================================= - High Availability refers to configurations that provide +High Availability refers to configurations that provide maximum network availability by having redundant or backup devices, links or switches between the host and the rest of the world. The goal is to provide the maximum availability of network connectivity @@ -2142,7 +2179,7 @@ could provide higher throughput. 11.1 High Availability in a Single Switch Topology -------------------------------------------------- - If two hosts (or a host and a single switch) are directly +If two hosts (or a host and a single switch) are directly connected via multiple physical links, then there is no availability penalty to optimizing for maximum bandwidth. In this case, there is only one switch (or peer), so if it fails, there is no alternative @@ -2150,32 +2187,32 @@ access to fail over to. Additionally, the bonding load balance modes support link monitoring of their members, so if individual links fail, the load will be rebalanced across the remaining devices. - See Section 12, "Configuring Bonding for Maximum Throughput" +See Section 12, "Configuring Bonding for Maximum Throughput" for information on configuring bonding with one peer device. 11.2 High Availability in a Multiple Switch Topology ---------------------------------------------------- - With multiple switches, the configuration of bonding and the +With multiple switches, the configuration of bonding and the network changes dramatically. In multiple switch topologies, there is a trade off between network availability and usable bandwidth. - Below is a sample network, configured to maximize the -availability of the network: +Below is a sample network, configured to maximize the +availability of the network:: - | | - |port3 port3| - +-----+----+ +-----+----+ - | |port2 ISL port2| | - | switch A +--------------------------+ switch B | - | | | | - +-----+----+ +-----++---+ - |port1 port1| - | +-------+ | - +-------------+ host1 +---------------+ - eth0 +-------+ eth1 + | | + |port3 port3| + +-----+----+ +-----+----+ + | |port2 ISL port2| | + | switch A +--------------------------+ switch B | + | | | | + +-----+----+ +-----++---+ + |port1 port1| + | +-------+ | + +-------------+ host1 +---------------+ + eth0 +-------+ eth1 - In this configuration, there is a link between the two +In this configuration, there is a link between the two switches (ISL, or inter switch link), and multiple ports connecting to the outside world ("port3" on each switch). There is no technical reason that this could not be extended to a third switch. @@ -2183,19 +2220,21 @@ reason that this could not be extended to a third switch. 11.2.1 HA Bonding Mode Selection for Multiple Switch Topology ------------------------------------------------------------- - In a topology such as the example above, the active-backup and +In a topology such as the example above, the active-backup and broadcast modes are the only useful bonding modes when optimizing for availability; the other modes require all links to terminate on the same peer for them to behave rationally. -active-backup: This is generally the preferred mode, particularly if +active-backup: + This is generally the preferred mode, particularly if the switches have an ISL and play together well. If the network configuration is such that one switch is specifically a backup switch (e.g., has lower capacity, higher cost, etc), then the primary option can be used to insure that the preferred link is always used when it is available. -broadcast: This mode is really a special purpose mode, and is suitable +broadcast: + This mode is really a special purpose mode, and is suitable only for very specific needs. For example, if the two switches are not connected (no ISL), and the networks beyond them are totally independent. In this case, if it is @@ -2205,7 +2244,7 @@ broadcast: This mode is really a special purpose mode, and is suitable 11.2.2 HA Link Monitoring Selection for Multiple Switch Topology ---------------------------------------------------------------- - The choice of link monitoring ultimately depends upon your +The choice of link monitoring ultimately depends upon your switch. If the switch can reliably fail ports in response to other failures, then either the MII or ARP monitors should work. For example, in the above example, if the "port3" link fails at the remote @@ -2213,7 +2252,7 @@ end, the MII monitor has no direct means to detect this. The ARP monitor could be configured with a target at the remote end of port3, thus detecting that failure without switch support. - In general, however, in a multiple switch topology, the ARP +In general, however, in a multiple switch topology, the ARP monitor can provide a higher level of reliability in detecting end to end connectivity failures (which may be caused by the failure of any individual component to pass traffic for any reason). Additionally, @@ -2222,7 +2261,7 @@ one for each switch in the network). This will insure that, regardless of which switch is active, the ARP monitor has a suitable target to query. - Note, also, that of late many switches now support a functionality +Note, also, that of late many switches now support a functionality generally referred to as "trunk failover." This is a feature of the switch that causes the link state of a particular switch port to be set down (or up) when the state of another switch port goes down (or up). @@ -2238,18 +2277,18 @@ suitable switches. 12.1 Maximizing Throughput in a Single Switch Topology ------------------------------------------------------ - In a single switch configuration, the best method to maximize +In a single switch configuration, the best method to maximize throughput depends upon the application and network environment. The various load balancing modes each have strengths and weaknesses in different environments, as detailed below. - For this discussion, we will break down the topologies into +For this discussion, we will break down the topologies into two categories. Depending upon the destination of most traffic, we categorize them into either "gatewayed" or "local" configurations. - In a gatewayed configuration, the "switch" is acting primarily +In a gatewayed configuration, the "switch" is acting primarily as a router, and the majority of traffic passes through this router to -other networks. An example would be the following: +other networks. An example would be the following:: +----------+ +----------+ @@ -2259,25 +2298,25 @@ other networks. An example would be the following: | |eth1 port2| | here somewhere +----------+ +----------+ - The router may be a dedicated router device, or another host +The router may be a dedicated router device, or another host acting as a gateway. For our discussion, the important point is that the majority of traffic from Host A will pass through the router to some other network before reaching its final destination. - In a gatewayed network configuration, although Host A may +In a gatewayed network configuration, although Host A may communicate with many other systems, all of its traffic will be sent and received via one other peer on the local network, the router. - Note that the case of two systems connected directly via +Note that the case of two systems connected directly via multiple physical links is, for purposes of configuring bonding, the same as a gatewayed configuration. In that case, it happens that all traffic is destined for the "gateway" itself, not some other network beyond the gateway. - In a local configuration, the "switch" is acting primarily as +In a local configuration, the "switch" is acting primarily as a switch, and the majority of traffic passes through this switch to reach other stations on the same network. An example would be the -following: +following:: +----------+ +----------+ +--------+ | |eth0 port1| +-------+ Host B | @@ -2287,19 +2326,19 @@ following: +----------+ +----------+port4 +--------+ - Again, the switch may be a dedicated switch device, or another +Again, the switch may be a dedicated switch device, or another host acting as a gateway. For our discussion, the important point is that the majority of traffic from Host A is destined for other hosts on the same local network (Hosts B and C in the above example). - In summary, in a gatewayed configuration, traffic to and from +In summary, in a gatewayed configuration, traffic to and from the bonded device will be to the same MAC level peer on the network (the gateway itself, i.e., the router), regardless of its final destination. In a local configuration, traffic flows directly to and from the final destinations, thus, each destination (Host B, Host C) will be addressed directly by their individual MAC addresses. - This distinction between a gatewayed and a local network +This distinction between a gatewayed and a local network configuration is important because many of the load balancing modes available use the MAC addresses of the local network source and destination to make load balancing decisions. The behavior of each @@ -2309,11 +2348,12 @@ mode is described below. 12.1.1 MT Bonding Mode Selection for Single Switch Topology ----------------------------------------------------------- - This configuration is the easiest to set up and to understand, +This configuration is the easiest to set up and to understand, although you will have to decide which bonding mode best suits your needs. The trade offs for each mode are detailed below: -balance-rr: This mode is the only mode that will permit a single +balance-rr: + This mode is the only mode that will permit a single TCP/IP connection to stripe traffic across multiple interfaces. It is therefore the only mode that will allow a single TCP/IP stream to utilize more than one interface's @@ -2351,7 +2391,8 @@ balance-rr: This mode is the only mode that will permit a single This mode requires the switch to have the appropriate ports configured for "etherchannel" or "trunking." -active-backup: There is not much advantage in this network topology to +active-backup: + There is not much advantage in this network topology to the active-backup mode, as the inactive backup devices are all connected to the same peer as the primary. In this case, a load balancing mode (with link monitoring) will provide the @@ -2361,7 +2402,8 @@ active-backup: There is not much advantage in this network topology to have value if the hardware available does not support any of the load balance modes. -balance-xor: This mode will limit traffic such that packets destined +balance-xor: + This mode will limit traffic such that packets destined for specific peers will always be sent over the same interface. Since the destination is determined by the MAC addresses involved, this mode works best in a "local" network @@ -2373,10 +2415,12 @@ balance-xor: This mode will limit traffic such that packets destined As with balance-rr, the switch ports need to be configured for "etherchannel" or "trunking." -broadcast: Like active-backup, there is not much advantage to this +broadcast: + Like active-backup, there is not much advantage to this mode in this type of network topology. -802.3ad: This mode can be a good choice for this type of network +802.3ad: + This mode can be a good choice for this type of network topology. The 802.3ad mode is an IEEE standard, so all peers that implement 802.3ad should interoperate well. The 802.3ad protocol includes automatic configuration of the aggregates, @@ -2390,7 +2434,7 @@ broadcast: Like active-backup, there is not much advantage to this the same speed and duplex. Also, as with all bonding load balance modes other than balance-rr, no single connection will be able to utilize more than a single interface's worth of - bandwidth. + bandwidth. Additionally, the linux bonding 802.3ad implementation distributes traffic by peer (using an XOR of MAC addresses @@ -2404,7 +2448,8 @@ broadcast: Like active-backup, there is not much advantage to this Finally, the 802.3ad mode mandates the use of the MII monitor, therefore, the ARP monitor is not available in this mode. -balance-tlb: The balance-tlb mode balances outgoing traffic by peer. +balance-tlb: + The balance-tlb mode balances outgoing traffic by peer. Since the balancing is done according to MAC address, in a "gatewayed" configuration (as described above), this mode will send all traffic across a single device. However, in a @@ -2422,7 +2467,8 @@ balance-tlb: The balance-tlb mode balances outgoing traffic by peer. network device driver of the slave interfaces, and the ARP monitor is not available. -balance-alb: This mode is everything that balance-tlb is, and more. +balance-alb: + This mode is everything that balance-tlb is, and more. It has all of the features (and restrictions) of balance-tlb, and will also balance incoming traffic from local network peers (as described in the Bonding Module Options section, @@ -2435,7 +2481,7 @@ balance-alb: This mode is everything that balance-tlb is, and more. 12.1.2 MT Link Monitoring for Single Switch Topology ---------------------------------------------------- - The choice of link monitoring may largely depend upon which +The choice of link monitoring may largely depend upon which mode you choose to use. The more advanced load balancing modes do not support the use of the ARP monitor, and are thus restricted to using the MII monitor (which does not provide as high a level of end to end @@ -2444,27 +2490,27 @@ assurance as the ARP monitor). 12.2 Maximum Throughput in a Multiple Switch Topology ----------------------------------------------------- - Multiple switches may be utilized to optimize for throughput +Multiple switches may be utilized to optimize for throughput when they are configured in parallel as part of an isolated network -between two or more systems, for example: +between two or more systems, for example:: - +-----------+ - | Host A | - +-+---+---+-+ - | | | - +--------+ | +---------+ - | | | - +------+---+ +-----+----+ +-----+----+ - | Switch A | | Switch B | | Switch C | - +------+---+ +-----+----+ +-----+----+ - | | | - +--------+ | +---------+ - | | | - +-+---+---+-+ - | Host B | - +-----------+ + +-----------+ + | Host A | + +-+---+---+-+ + | | | + +--------+ | +---------+ + | | | + +------+---+ +-----+----+ +-----+----+ + | Switch A | | Switch B | | Switch C | + +------+---+ +-----+----+ +-----+----+ + | | | + +--------+ | +---------+ + | | | + +-+---+---+-+ + | Host B | + +-----------+ - In this configuration, the switches are isolated from one +In this configuration, the switches are isolated from one another. One reason to employ a topology such as this is for an isolated network with many hosts (a cluster configured for high performance, for example), using multiple smaller switches can be more @@ -2472,14 +2518,14 @@ cost effective than a single larger switch, e.g., on a network with 24 hosts, three 24 port switches can be significantly less expensive than a single 72 port switch. - If access beyond the network is required, an individual host +If access beyond the network is required, an individual host can be equipped with an additional network device connected to an external network; this host then additionally acts as a gateway. 12.2.1 MT Bonding Mode Selection for Multiple Switch Topology ------------------------------------------------------------- - In actual practice, the bonding mode typically employed in +In actual practice, the bonding mode typically employed in configurations of this type is balance-rr. Historically, in this network configuration, the usual caveats about out of order packet delivery are mitigated by the use of network adapters that do not do @@ -2492,7 +2538,7 @@ utilize greater than one interface's bandwidth. 12.2.2 MT Link Monitoring for Multiple Switch Topology ------------------------------------------------------ - Again, in actual practice, the MII monitor is most often used +Again, in actual practice, the MII monitor is most often used in this configuration, as performance is given preference over availability. The ARP monitor will function in this topology, but its advantages over the MII monitor are mitigated by the volume of probes @@ -2505,10 +2551,10 @@ host in the network is configured with bonding). 13.1 Link Establishment and Failover Delays ------------------------------------------- - Some switches exhibit undesirable behavior with regard to the +Some switches exhibit undesirable behavior with regard to the timing of link up and down reporting by the switch. - First, when a link comes up, some switches may indicate that +First, when a link comes up, some switches may indicate that the link is up (carrier available), but not pass traffic over the interface for some period of time. This delay is typically due to some type of autonegotiation or routing protocol, but may also occur @@ -2517,12 +2563,12 @@ failure). If you find this to be a problem, specify an appropriate value to the updelay bonding module option to delay the use of the relevant interface(s). - Second, some switches may "bounce" the link state one or more +Second, some switches may "bounce" the link state one or more times while a link is changing state. This occurs most commonly while the switch is initializing. Again, an appropriate updelay value may help. - Note that when a bonding interface has no active links, the +Note that when a bonding interface has no active links, the driver will immediately reuse the first link that goes up, even if the updelay parameter has been specified (the updelay is ignored in this case). If there are slave interfaces waiting for the updelay timeout @@ -2532,7 +2578,7 @@ value of updelay has been overestimated, and since this occurs only in cases with no connectivity, there is no additional penalty for ignoring the updelay. - In addition to the concerns about switch timings, if your +In addition to the concerns about switch timings, if your switches take a long time to go into backup mode, it may be desirable to not activate a backup interface immediately after a link goes down. Failover may be delayed via the downdelay bonding module option. @@ -2540,31 +2586,31 @@ Failover may be delayed via the downdelay bonding module option. 13.2 Duplicated Incoming Packets -------------------------------- - NOTE: Starting with version 3.0.2, the bonding driver has logic to +NOTE: Starting with version 3.0.2, the bonding driver has logic to suppress duplicate packets, which should largely eliminate this problem. The following description is kept for reference. - It is not uncommon to observe a short burst of duplicated +It is not uncommon to observe a short burst of duplicated traffic when the bonding device is first used, or after it has been idle for some period of time. This is most easily observed by issuing a "ping" to some other host on the network, and noticing that the output from ping flags duplicates (typically one per slave). - For example, on a bond in active-backup mode with five slaves -all connected to one switch, the output may appear as follows: +For example, on a bond in active-backup mode with five slaves +all connected to one switch, the output may appear as follows:: -# ping -n 10.0.4.2 -PING 10.0.4.2 (10.0.4.2) from 10.0.3.10 : 56(84) bytes of data. -64 bytes from 10.0.4.2: icmp_seq=1 ttl=64 time=13.7 ms -64 bytes from 10.0.4.2: icmp_seq=1 ttl=64 time=13.8 ms (DUP!) -64 bytes from 10.0.4.2: icmp_seq=1 ttl=64 time=13.8 ms (DUP!) -64 bytes from 10.0.4.2: icmp_seq=1 ttl=64 time=13.8 ms (DUP!) -64 bytes from 10.0.4.2: icmp_seq=1 ttl=64 time=13.8 ms (DUP!) -64 bytes from 10.0.4.2: icmp_seq=2 ttl=64 time=0.216 ms -64 bytes from 10.0.4.2: icmp_seq=3 ttl=64 time=0.267 ms -64 bytes from 10.0.4.2: icmp_seq=4 ttl=64 time=0.222 ms + # ping -n 10.0.4.2 + PING 10.0.4.2 (10.0.4.2) from 10.0.3.10 : 56(84) bytes of data. + 64 bytes from 10.0.4.2: icmp_seq=1 ttl=64 time=13.7 ms + 64 bytes from 10.0.4.2: icmp_seq=1 ttl=64 time=13.8 ms (DUP!) + 64 bytes from 10.0.4.2: icmp_seq=1 ttl=64 time=13.8 ms (DUP!) + 64 bytes from 10.0.4.2: icmp_seq=1 ttl=64 time=13.8 ms (DUP!) + 64 bytes from 10.0.4.2: icmp_seq=1 ttl=64 time=13.8 ms (DUP!) + 64 bytes from 10.0.4.2: icmp_seq=2 ttl=64 time=0.216 ms + 64 bytes from 10.0.4.2: icmp_seq=3 ttl=64 time=0.267 ms + 64 bytes from 10.0.4.2: icmp_seq=4 ttl=64 time=0.222 ms - This is not due to an error in the bonding driver, rather, it +This is not due to an error in the bonding driver, rather, it is a side effect of how many switches update their MAC forwarding tables. Initially, the switch does not associate the MAC address in the packet with a particular switch port, and so it may send the @@ -2574,7 +2620,7 @@ single switch, when the switch (temporarily) floods the traffic to all ports, the bond device receives multiple copies of the same packet (one per slave device). - The duplicated packet behavior is switch dependent, some +The duplicated packet behavior is switch dependent, some switches exhibit this, and some do not. On switches that display this behavior, it can be induced by clearing the MAC forwarding table (on most Cisco switches, the privileged command "clear mac address-table @@ -2583,16 +2629,16 @@ dynamic" will accomplish this). 14. Hardware Specific Considerations ==================================== - This section contains additional information for configuring +This section contains additional information for configuring bonding on specific hardware platforms, or for interfacing bonding with particular switches or other devices. 14.1 IBM BladeCenter -------------------- - This applies to the JS20 and similar systems. +This applies to the JS20 and similar systems. - On the JS20 blades, the bonding driver supports only +On the JS20 blades, the bonding driver supports only balance-rr, active-backup, balance-tlb and balance-alb modes. This is largely due to the network topology inside the BladeCenter, detailed below. @@ -2600,7 +2646,7 @@ below. JS20 network adapter information -------------------------------- - All JS20s come with two Broadcom Gigabit Ethernet ports +All JS20s come with two Broadcom Gigabit Ethernet ports integrated on the planar (that's "motherboard" in IBM-speak). In the BladeCenter chassis, the eth0 port of all JS20 blades is hard wired to I/O Module #1; similarly, all eth1 ports are wired to I/O Module #2. @@ -2608,36 +2654,36 @@ An add-on Broadcom daughter card can be installed on a JS20 to provide two more Gigabit Ethernet ports. These ports, eth2 and eth3, are wired to I/O Modules 3 and 4, respectively. - Each I/O Module may contain either a switch or a passthrough +Each I/O Module may contain either a switch or a passthrough module (which allows ports to be directly connected to an external switch). Some bonding modes require a specific BladeCenter internal network topology in order to function; these are detailed below. - Additional BladeCenter-specific networking information can be +Additional BladeCenter-specific networking information can be found in two IBM Redbooks (www.ibm.com/redbooks): -"IBM eServer BladeCenter Networking Options" -"IBM eServer BladeCenter Layer 2-7 Network Switching" +- "IBM eServer BladeCenter Networking Options" +- "IBM eServer BladeCenter Layer 2-7 Network Switching" BladeCenter networking configuration ------------------------------------ - Because a BladeCenter can be configured in a very large number +Because a BladeCenter can be configured in a very large number of ways, this discussion will be confined to describing basic configurations. - Normally, Ethernet Switch Modules (ESMs) are used in I/O +Normally, Ethernet Switch Modules (ESMs) are used in I/O modules 1 and 2. In this configuration, the eth0 and eth1 ports of a JS20 will be connected to different internal switches (in the respective I/O modules). - A passthrough module (OPM or CPM, optical or copper, +A passthrough module (OPM or CPM, optical or copper, passthrough module) connects the I/O module directly to an external switch. By using PMs in I/O module #1 and #2, the eth0 and eth1 interfaces of a JS20 can be redirected to the outside world and connected to a common external switch. - Depending upon the mix of ESMs and PMs, the network will +Depending upon the mix of ESMs and PMs, the network will appear to bonding as either a single switch topology (all PMs) or as a multiple switch topology (one or more ESMs, zero or more PMs). It is also possible to connect ESMs together, resulting in a configuration @@ -2647,24 +2693,24 @@ Topology," above. Requirements for specific modes ------------------------------- - The balance-rr mode requires the use of passthrough modules +The balance-rr mode requires the use of passthrough modules for devices in the bond, all connected to an common external switch. That switch must be configured for "etherchannel" or "trunking" on the appropriate ports, as is usual for balance-rr. - The balance-alb and balance-tlb modes will function with +The balance-alb and balance-tlb modes will function with either switch modules or passthrough modules (or a mix). The only specific requirement for these modes is that all network interfaces must be able to reach all destinations for traffic sent over the bonding device (i.e., the network must converge at some point outside the BladeCenter). - The active-backup mode has no additional requirements. +The active-backup mode has no additional requirements. Link monitoring issues ---------------------- - When an Ethernet Switch Module is in place, only the ARP +When an Ethernet Switch Module is in place, only the ARP monitor will reliably detect link loss to an external switch. This is nothing unusual, but examination of the BladeCenter cabinet would suggest that the "external" network ports are the ethernet ports for @@ -2672,166 +2718,173 @@ the system, when it fact there is a switch between these "external" ports and the devices on the JS20 system itself. The MII monitor is only able to detect link failures between the ESM and the JS20 system. - When a passthrough module is in place, the MII monitor does +When a passthrough module is in place, the MII monitor does detect failures to the "external" port, which is then directly connected to the JS20 system. Other concerns -------------- - The Serial Over LAN (SoL) link is established over the primary +The Serial Over LAN (SoL) link is established over the primary ethernet (eth0) only, therefore, any loss of link to eth0 will result in losing your SoL connection. It will not fail over with other network traffic, as the SoL system is beyond the control of the bonding driver. - It may be desirable to disable spanning tree on the switch +It may be desirable to disable spanning tree on the switch (either the internal Ethernet Switch Module, or an external switch) to avoid fail-over delay issues when using bonding. - + 15. Frequently Asked Questions ============================== 1. Is it SMP safe? +------------------- - Yes. The old 2.0.xx channel bonding patch was not SMP safe. +Yes. The old 2.0.xx channel bonding patch was not SMP safe. The new driver was designed to be SMP safe from the start. 2. What type of cards will work with it? +----------------------------------------- - Any Ethernet type cards (you can even mix cards - a Intel +Any Ethernet type cards (you can even mix cards - a Intel EtherExpress PRO/100 and a 3com 3c905b, for example). For most modes, devices need not be of the same speed. - Starting with version 3.2.1, bonding also supports Infiniband +Starting with version 3.2.1, bonding also supports Infiniband slaves in active-backup mode. 3. How many bonding devices can I have? +---------------------------------------- - There is no limit. +There is no limit. 4. How many slaves can a bonding device have? +---------------------------------------------- - This is limited only by the number of network interfaces Linux +This is limited only by the number of network interfaces Linux supports and/or the number of network cards you can place in your system. 5. What happens when a slave link dies? +---------------------------------------- - If link monitoring is enabled, then the failing device will be +If link monitoring is enabled, then the failing device will be disabled. The active-backup mode will fail over to a backup link, and other modes will ignore the failed link. The link will continue to be monitored, and should it recover, it will rejoin the bond (in whatever manner is appropriate for the mode). See the sections on High Availability and the documentation for each mode for additional information. - - Link monitoring can be enabled via either the miimon or + +Link monitoring can be enabled via either the miimon or arp_interval parameters (described in the module parameters section, above). In general, miimon monitors the carrier state as sensed by the underlying network device, and the arp monitor (arp_interval) monitors connectivity to another host on the local network. - If no link monitoring is configured, the bonding driver will +If no link monitoring is configured, the bonding driver will be unable to detect link failures, and will assume that all links are always available. This will likely result in lost packets, and a resulting degradation of performance. The precise performance loss depends upon the bonding mode and network configuration. 6. Can bonding be used for High Availability? +---------------------------------------------- - Yes. See the section on High Availability for details. +Yes. See the section on High Availability for details. 7. Which switches/systems does it work with? +--------------------------------------------- - The full answer to this depends upon the desired mode. +The full answer to this depends upon the desired mode. - In the basic balance modes (balance-rr and balance-xor), it +In the basic balance modes (balance-rr and balance-xor), it works with any system that supports etherchannel (also called trunking). Most managed switches currently available have such support, and many unmanaged switches as well. - The advanced balance modes (balance-tlb and balance-alb) do +The advanced balance modes (balance-tlb and balance-alb) do not have special switch requirements, but do need device drivers that support specific features (described in the appropriate section under module parameters, above). - In 802.3ad mode, it works with systems that support IEEE +In 802.3ad mode, it works with systems that support IEEE 802.3ad Dynamic Link Aggregation. Most managed and many unmanaged switches currently available support 802.3ad. - The active-backup mode should work with any Layer-II switch. +The active-backup mode should work with any Layer-II switch. 8. Where does a bonding device get its MAC address from? +--------------------------------------------------------- - When using slave devices that have fixed MAC addresses, or when +When using slave devices that have fixed MAC addresses, or when the fail_over_mac option is enabled, the bonding device's MAC address is the MAC address of the active slave. - For other configurations, if not explicitly configured (with +For other configurations, if not explicitly configured (with ifconfig or ip link), the MAC address of the bonding device is taken from its first slave device. This MAC address is then passed to all following slaves and remains persistent (even if the first slave is removed) until the bonding device is brought down or reconfigured. - If you wish to change the MAC address, you can set it with -ifconfig or ip link: +If you wish to change the MAC address, you can set it with +ifconfig or ip link:: -# ifconfig bond0 hw ether 00:11:22:33:44:55 + # ifconfig bond0 hw ether 00:11:22:33:44:55 -# ip link set bond0 address 66:77:88:99:aa:bb + # ip link set bond0 address 66:77:88:99:aa:bb - The MAC address can be also changed by bringing down/up the -device and then changing its slaves (or their order): +The MAC address can be also changed by bringing down/up the +device and then changing its slaves (or their order):: -# ifconfig bond0 down ; modprobe -r bonding -# ifconfig bond0 .... up -# ifenslave bond0 eth... + # ifconfig bond0 down ; modprobe -r bonding + # ifconfig bond0 .... up + # ifenslave bond0 eth... - This method will automatically take the address from the next +This method will automatically take the address from the next slave that is added. - To restore your slaves' MAC addresses, you need to detach them -from the bond (`ifenslave -d bond0 eth0'). The bonding driver will +To restore your slaves' MAC addresses, you need to detach them +from the bond (``ifenslave -d bond0 eth0``). The bonding driver will then restore the MAC addresses that the slaves had before they were enslaved. 16. Resources and Links ======================= - The latest version of the bonding driver can be found in the latest +The latest version of the bonding driver can be found in the latest version of the linux kernel, found on http://kernel.org - The latest version of this document can be found in the latest kernel -source (named Documentation/networking/bonding.txt). +The latest version of this document can be found in the latest kernel +source (named Documentation/networking/bonding.rst). - Discussions regarding the usage of the bonding driver take place on the +Discussions regarding the usage of the bonding driver take place on the bonding-devel mailing list, hosted at sourceforge.net. If you have questions or problems, post them to the list. The list address is: bonding-devel@lists.sourceforge.net - The administrative interface (to subscribe or unsubscribe) can +The administrative interface (to subscribe or unsubscribe) can be found at: https://lists.sourceforge.net/lists/listinfo/bonding-devel - Discussions regarding the development of the bonding driver take place +Discussions regarding the development of the bonding driver take place on the main Linux network mailing list, hosted at vger.kernel.org. The list address is: netdev@vger.kernel.org - The administrative interface (to subscribe or unsubscribe) can +The administrative interface (to subscribe or unsubscribe) can be found at: http://vger.kernel.org/vger-lists.html#netdev Donald Becker's Ethernet Drivers and diag programs may be found at : - - http://web.archive.org/web/*/http://www.scyld.com/network/ + + - http://web.archive.org/web/%2E/http://www.scyld.com/network/ You will also find a lot of information regarding Ethernet, NWay, MII, etc. at www.scyld.com. - --- END -- diff --git a/Documentation/networking/device_drivers/intel/e100.rst b/Documentation/networking/device_drivers/intel/e100.rst index caf023cc88de..3ac21e7119a7 100644 --- a/Documentation/networking/device_drivers/intel/e100.rst +++ b/Documentation/networking/device_drivers/intel/e100.rst @@ -33,7 +33,7 @@ The following features are now available in supported kernels: - SNMP Channel Bonding documentation can be found in the Linux kernel source: -/Documentation/networking/bonding.txt +/Documentation/networking/bonding.rst Identifying Your Adapter diff --git a/Documentation/networking/device_drivers/intel/ixgb.rst b/Documentation/networking/device_drivers/intel/ixgb.rst index 945018207a92..ab624f1a44a8 100644 --- a/Documentation/networking/device_drivers/intel/ixgb.rst +++ b/Documentation/networking/device_drivers/intel/ixgb.rst @@ -37,7 +37,7 @@ The following features are available in this kernel: - SNMP Channel Bonding documentation can be found in the Linux kernel source: -/Documentation/networking/bonding.txt +/Documentation/networking/bonding.rst The driver information previously displayed in the /proc filesystem is not supported in this release. Alternatively, you can use ethtool (version 1.6 diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst index fbf845fbaff7..22b872834ef0 100644 --- a/Documentation/networking/index.rst +++ b/Documentation/networking/index.rst @@ -44,6 +44,7 @@ Contents: atm ax25 baycom + bonding .. only:: subproject and html diff --git a/drivers/net/Kconfig b/drivers/net/Kconfig index b103fbdd0f68..4ab6d343fd86 100644 --- a/drivers/net/Kconfig +++ b/drivers/net/Kconfig @@ -50,7 +50,7 @@ config BONDING The driver supports multiple bonding modes to allow for both high performance and high availability operation. - Refer to for more + Refer to for more information. To compile this driver as a module, choose M here: the module From patchwork Mon Apr 27 22:01:25 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Mauro Carvalho Chehab X-Patchwork-Id: 220445 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-10.1 required=3.0 tests=DKIMWL_WL_HIGH, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, INCLUDES_PATCH, MAILING_LIST_MULTI, SIGNED_OFF_BY, SPF_HELO_NONE, SPF_PASS, URIBL_BLOCKED, USER_AGENT_GIT autolearn=unavailable autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id BD266C82A00 for ; Mon, 27 Apr 2020 22:05:10 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 9680B208FE for ; Mon, 27 Apr 2020 22:05:10 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1588025110; bh=dF+NLkrSZQWpkJtyhjfUrm9LkyWHXe56pH8Wmk9Nu4o=; h=From:To:Cc:Subject:Date:In-Reply-To:References:List-ID:From; b=uZz7JchwF8dG0febdZEy++q2MOOmCgoi+2SojPGTNTfpEj4RNq5LVhWoYoOHtsjit xa5kxTZ8SScSEMrsJrvCrqHyO9TBJqqryhZWDpmKd+fCtIEY0Z9PoXE59aA6KZXdNd Ph2pTfitD8xXFEWBCtRz913bvb+7Xcfmv298Rk+s= Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1726964AbgD0WFD (ORCPT ); Mon, 27 Apr 2020 18:05:03 -0400 Received: from mail.kernel.org ([198.145.29.99]:48010 "EHLO mail.kernel.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726315AbgD0WB6 (ORCPT ); Mon, 27 Apr 2020 18:01:58 -0400 Received: from mail.kernel.org (ip5f5ad5c5.dynamic.kabel-deutschland.de [95.90.213.197]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPSA id 762962192A; Mon, 27 Apr 2020 22:01:56 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1588024916; bh=dF+NLkrSZQWpkJtyhjfUrm9LkyWHXe56pH8Wmk9Nu4o=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=06Eg8a1sFp9KQHIsNs+zJCs0vnN+rmscMvP6MI5I4pIxPUI+bmuPKS6x5PuVlBVJ1 bTfhyH8HLW7CHTPxHeDDgUnY6l9JFy17tO09/qtFJLQgX+wM6zQRmsFRofg4cKR0G8 kMLf3FKuUf7OhcQib517BMiDSQhZZEnRGdpHqjW0= Received: from mchehab by mail.kernel.org with local (Exim 4.92.3) (envelope-from ) id 1jTBp4-000IoR-OP; Tue, 28 Apr 2020 00:01:54 +0200 From: Mauro Carvalho Chehab To: Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Jonathan Corbet , "David S. Miller" , Jakub Kicinski , netdev@vger.kernel.org Subject: [PATCH 10/38] docs: networking: convert cdc_mbim.txt to ReST Date: Tue, 28 Apr 2020 00:01:25 +0200 Message-Id: X-Mailer: git-send-email 2.25.4 In-Reply-To: References: MIME-Version: 1.0 Sender: netdev-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: netdev@vger.kernel.org - add SPDX header; - mark code blocks and literals as such; - use :field: markup; - adjust identation, whitespaces and blank lines; - add to networking/index.rst. Signed-off-by: Mauro Carvalho Chehab --- .../networking/{cdc_mbim.txt => cdc_mbim.rst} | 76 +++++++++++-------- Documentation/networking/index.rst | 1 + 2 files changed, 47 insertions(+), 30 deletions(-) rename Documentation/networking/{cdc_mbim.txt => cdc_mbim.rst} (88%) diff --git a/Documentation/networking/cdc_mbim.txt b/Documentation/networking/cdc_mbim.rst similarity index 88% rename from Documentation/networking/cdc_mbim.txt rename to Documentation/networking/cdc_mbim.rst index 4e68f0bc5dba..0048409c06b4 100644 --- a/Documentation/networking/cdc_mbim.txt +++ b/Documentation/networking/cdc_mbim.rst @@ -1,5 +1,8 @@ - cdc_mbim - Driver for CDC MBIM Mobile Broadband modems - ======================================================== +.. SPDX-License-Identifier: GPL-2.0 + +====================================================== +cdc_mbim - Driver for CDC MBIM Mobile Broadband modems +====================================================== The cdc_mbim driver supports USB devices conforming to the "Universal Serial Bus Communications Class Subclass Specification for Mobile @@ -19,9 +22,9 @@ by a cdc_ncm driver parameter: prefer_mbim ----------- -Type: Boolean -Valid Range: N/Y (0-1) -Default Value: Y (MBIM is preferred) +:Type: Boolean +:Valid Range: N/Y (0-1) +:Default Value: Y (MBIM is preferred) This parameter sets the system policy for NCM/MBIM functions. Such functions will be handled by either the cdc_ncm driver or the cdc_mbim @@ -44,11 +47,13 @@ userspace MBIM management application always is required to enable a MBIM function. Such userspace applications includes, but are not limited to: + - mbimcli (included with the libmbim [3] library), and - ModemManager [4] Establishing a MBIM IP session reequires at least these actions by the management application: + - open the control channel - configure network connection settings - connect to network @@ -76,7 +81,7 @@ complies with all the control channel requirements in [1]. The cdc-wdmX device is created as a child of the MBIM control interface USB device. The character device associated with a specific -MBIM function can be looked up using sysfs. For example: +MBIM function can be looked up using sysfs. For example:: bjorn@nemi:~$ ls /sys/bus/usb/drivers/cdc_mbim/2-4:2.12/usbmisc cdc-wdm0 @@ -119,13 +124,15 @@ negotiated control message size. /dev/cdc-wdmX ioctl() --------------------- +--------------------- IOCTL_WDM_MAX_COMMAND: Get Maximum Command Size This ioctl returns the wMaxControlMessage field of the CDC MBIM functional descriptor for MBIM devices. This is intended as a convenience, eliminating the need to parse the USB descriptors from userspace. +:: + #include #include #include @@ -178,7 +185,7 @@ VLAN links prior to establishing MBIM IP sessions where the SessionId is greater than 0. These links can be added by using the normal VLAN kernel interfaces, either ioctl or netlink. -For example, adding a link for a MBIM IP session with SessionId 3: +For example, adding a link for a MBIM IP session with SessionId 3:: ip link add link wwan0 name wwan0.3 type vlan id 3 @@ -207,6 +214,7 @@ the stream to the end user in an appropriate way for the stream type. The network device ABI requires a dummy ethernet header for every DSS data frame being transported. The contents of this header is arbitrary, with the following exceptions: + - TX frames using an IP protocol (0x0800 or 0x86dd) will be dropped - RX frames will have the protocol field set to ETH_P_802_3 (but will not be properly formatted 802.3 frames) @@ -218,7 +226,7 @@ adding the dummy ethernet header on TX and stripping it on RX. This is a simple example using tools commonly available, exporting DssSessionId 5 as a pty character device pointed to by a /dev/nmea -symlink: +symlink:: ip link add link wwan0 name wwan0.dss5 type vlan id 261 ip link set dev wwan0.dss5 up @@ -236,7 +244,7 @@ map frames to the correct DSS session and adding 18 byte VLAN ethernet headers with the appropriate tag on TX. In this case using a socket filter is recommended, matching only the DSS VLAN subset. This avoid unnecessary copying of unrelated IP session data to userspace. For -example: +example:: static struct sock_filter dssfilter[] = { /* use special negative offsets to get VLAN tag */ @@ -249,11 +257,11 @@ example: BPF_JUMP(BPF_JMP|BPF_JGE|BPF_K, 512, 3, 0), /* 511 is last DSS VLAN */ /* verify ethertype */ - BPF_STMT(BPF_LD|BPF_H|BPF_ABS, 2 * ETH_ALEN), - BPF_JUMP(BPF_JMP|BPF_JEQ|BPF_K, ETH_P_802_3, 0, 1), + BPF_STMT(BPF_LD|BPF_H|BPF_ABS, 2 * ETH_ALEN), + BPF_JUMP(BPF_JMP|BPF_JEQ|BPF_K, ETH_P_802_3, 0, 1), - BPF_STMT(BPF_RET|BPF_K, (u_int)-1), /* accept */ - BPF_STMT(BPF_RET|BPF_K, 0), /* ignore */ + BPF_STMT(BPF_RET|BPF_K, (u_int)-1), /* accept */ + BPF_STMT(BPF_RET|BPF_K, 0), /* ignore */ }; @@ -266,6 +274,7 @@ network device. This mapping implies a few restrictions on multiplexed IPS and DSS sessions, which may not always be practical: + - no IPS or DSS session can use a frame size greater than the MTU on IP session 0 - no IPS or DSS session can be in the up state unless the network @@ -280,7 +289,7 @@ device. Tip: It might be less confusing to the end user to name this VLAN subdevice after the MBIM SessionID instead of the VLAN ID. For -example: +example:: ip link add link wwan0 name wwan0.0 type vlan id 4094 @@ -290,7 +299,7 @@ VLAN mapping Summarizing the cdc_mbim driver mapping described above, we have this relationship between VLAN tags on the wwanY network device and MBIM -sessions on the shared USB data channel: +sessions on the shared USB data channel:: VLAN ID MBIM type MBIM SessionID Notes --------------------------------------------------------- @@ -310,30 +319,37 @@ sessions on the shared USB data channel: References ========== -[1] USB Implementers Forum, Inc. - "Universal Serial Bus - Communications Class Subclass Specification for Mobile Broadband - Interface Model", Revision 1.0 (Errata 1), May 1, 2013 + 1) USB Implementers Forum, Inc. - "Universal Serial Bus + Communications Class Subclass Specification for Mobile Broadband + Interface Model", Revision 1.0 (Errata 1), May 1, 2013 + - http://www.usb.org/developers/docs/devclass_docs/ -[2] USB Implementers Forum, Inc. - "Universal Serial Bus - Communications Class Subclass Specifications for Network Control - Model Devices", Revision 1.0 (Errata 1), November 24, 2010 + 2) USB Implementers Forum, Inc. - "Universal Serial Bus + Communications Class Subclass Specifications for Network Control + Model Devices", Revision 1.0 (Errata 1), November 24, 2010 + - http://www.usb.org/developers/docs/devclass_docs/ -[3] libmbim - "a glib-based library for talking to WWAN modems and - devices which speak the Mobile Interface Broadband Model (MBIM) - protocol" + 3) libmbim - "a glib-based library for talking to WWAN modems and + devices which speak the Mobile Interface Broadband Model (MBIM) + protocol" + - http://www.freedesktop.org/wiki/Software/libmbim/ -[4] ModemManager - "a DBus-activated daemon which controls mobile - broadband (2G/3G/4G) devices and connections" + 4) ModemManager - "a DBus-activated daemon which controls mobile + broadband (2G/3G/4G) devices and connections" + - http://www.freedesktop.org/wiki/Software/ModemManager/ -[5] "MBIM (Mobile Broadband Interface Model) Registry" + 5) "MBIM (Mobile Broadband Interface Model) Registry" + - http://compliance.usb.org/mbim/ -[6] "/sys/kernel/debug/usb/devices output format" + 6) "/sys/kernel/debug/usb/devices output format" + - Documentation/driver-api/usb/usb.rst -[7] "/sys/bus/usb/devices/.../descriptors" + 7) "/sys/bus/usb/devices/.../descriptors" + - Documentation/ABI/stable/sysfs-bus-usb diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst index 22b872834ef0..55802abd65a0 100644 --- a/Documentation/networking/index.rst +++ b/Documentation/networking/index.rst @@ -45,6 +45,7 @@ Contents: ax25 baycom bonding + cdc_mbim .. only:: subproject and html From patchwork Mon Apr 27 22:01:26 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Mauro Carvalho Chehab X-Patchwork-Id: 220443 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-10.1 required=3.0 tests=DKIMWL_WL_HIGH, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, INCLUDES_PATCH, MAILING_LIST_MULTI, SIGNED_OFF_BY, SPF_HELO_NONE, SPF_PASS, URIBL_BLOCKED, USER_AGENT_GIT autolearn=unavailable autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id D1E42C82A01 for ; Mon, 27 Apr 2020 22:05:29 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id A837E208FE for ; Mon, 27 Apr 2020 22:05:29 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1588025129; bh=aaALIx74QyjMbTVhHHG9pqdXWwDu+Zs5Jrf90Sc9+jM=; h=From:To:Cc:Subject:Date:In-Reply-To:References:List-ID:From; b=e4xS1E3S8xbHwbiIRAW/uQZepqTuQNviUPCpE2Y6DP241+DMHI/sUfZ7i2vy/7tHj 0zGsWmlQTD80kXONgqEDhj8VGEKJqbkO2v0xxA8FnIytb/S7ovdBzU/Bj6t17f3Xnm pvIkjUDPW7tqh6/B3UA5R1pXIMtI1FuIJ9740R9s= Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1726982AbgD0WFT (ORCPT ); Mon, 27 Apr 2020 18:05:19 -0400 Received: from mail.kernel.org ([198.145.29.99]:47992 "EHLO mail.kernel.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726307AbgD0WB6 (ORCPT ); Mon, 27 Apr 2020 18:01:58 -0400 Received: from mail.kernel.org (ip5f5ad5c5.dynamic.kabel-deutschland.de [95.90.213.197]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPSA id 79A0321973; Mon, 27 Apr 2020 22:01:56 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1588024916; bh=aaALIx74QyjMbTVhHHG9pqdXWwDu+Zs5Jrf90Sc9+jM=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=x3T95GqEXv+hpJG+/s9XJaXw8WQgMn4tXNqP92KsD3ITby9j7kwRs+OWTaJC9mVDX IlMmpLwiReQh4MDUpMxv0gYPaoeZGp+/Cj8+MYwyHI670D7CrIEjflbkp90d/EpCi4 zPc2blBbgOhhbt7/fwGvCCx70ayyCxIVOk4QJP4k= Received: from mchehab by mail.kernel.org with local (Exim 4.92.3) (envelope-from ) id 1jTBp4-000IoV-PD; Tue, 28 Apr 2020 00:01:54 +0200 From: Mauro Carvalho Chehab To: Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Jonathan Corbet , "David S. Miller" , Jakub Kicinski , netdev@vger.kernel.org Subject: [PATCH 11/38] docs: networking: convert cops.txt to ReST Date: Tue, 28 Apr 2020 00:01:26 +0200 Message-Id: <26d3a3792de65e8a0c5ad3ac40b8146fa809c45a.1588024424.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.25.4 In-Reply-To: References: MIME-Version: 1.0 Sender: netdev-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: netdev@vger.kernel.org - add SPDX header; - adjust titles and chapters, adding proper markups; - mark code blocks and literals as such; - adjust identation, whitespaces and blank lines; - add to networking/index.rst. Signed-off-by: Mauro Carvalho Chehab --- Documentation/networking/cops.rst | 80 ++++++++++++++++++++++++++++++ Documentation/networking/cops.txt | 63 ----------------------- Documentation/networking/index.rst | 1 + drivers/net/appletalk/Kconfig | 2 +- 4 files changed, 82 insertions(+), 64 deletions(-) create mode 100644 Documentation/networking/cops.rst delete mode 100644 Documentation/networking/cops.txt diff --git a/Documentation/networking/cops.rst b/Documentation/networking/cops.rst new file mode 100644 index 000000000000..964ba80599a9 --- /dev/null +++ b/Documentation/networking/cops.rst @@ -0,0 +1,80 @@ +.. SPDX-License-Identifier: GPL-2.0 + +======================================== +The COPS LocalTalk Linux driver (cops.c) +======================================== + +By Jay Schulist + +This driver has two modes and they are: Dayna mode and Tangent mode. +Each mode corresponds with the type of card. It has been found +that there are 2 main types of cards and all other cards are +the same and just have different names or only have minor differences +such as more IO ports. As this driver is tested it will +become more clear exactly what cards are supported. + +Right now these cards are known to work with the COPS driver. The +LT-200 cards work in a somewhat more limited capacity than the +DL200 cards, which work very well and are in use by many people. + +TANGENT driver mode: + - Tangent ATB-II, Novell NL-1000, Daystar Digital LT-200 + +DAYNA driver mode: + - Dayna DL2000/DaynaTalk PC (Half Length), COPS LT-95, + - Farallon PhoneNET PC III, Farallon PhoneNET PC II + +Other cards possibly supported mode unknown though: + - Dayna DL2000 (Full length) + +The COPS driver defaults to using Dayna mode. To change the driver's +mode if you built a driver with dual support use board_type=1 or +board_type=2 for Dayna or Tangent with insmod. + +Operation/loading of the driver +=============================== + +Use modprobe like this: /sbin/modprobe cops.o (IO #) (IRQ #) +If you do not specify any options the driver will try and use the IO = 0x240, +IRQ = 5. As of right now I would only use IRQ 5 for the card, if autoprobing. + +To load multiple COPS driver Localtalk cards you can do one of the following:: + + insmod cops io=0x240 irq=5 + insmod -o cops2 cops io=0x260 irq=3 + +Or in lilo.conf put something like this:: + + append="ether=5,0x240,lt0 ether=3,0x260,lt1" + +Then bring up the interface with ifconfig. It will look something like this:: + + lt0 Link encap:UNSPEC HWaddr 00-00-00-00-00-00-00-F7-00-00-00-00-00-00-00-00 + inet addr:192.168.1.2 Bcast:192.168.1.255 Mask:255.255.255.0 + UP BROADCAST RUNNING NOARP MULTICAST MTU:600 Metric:1 + RX packets:0 errors:0 dropped:0 overruns:0 frame:0 + TX packets:0 errors:0 dropped:0 overruns:0 carrier:0 coll:0 + +Netatalk Configuration +====================== + +You will need to configure atalkd with something like the following to make +it work with the cops.c driver. + +* For single LTalk card use:: + + dummy -seed -phase 2 -net 2000 -addr 2000.10 -zone "1033" + lt0 -seed -phase 1 -net 1000 -addr 1000.50 -zone "1033" + +* For multiple cards, Ethernet and LocalTalk:: + + eth0 -seed -phase 2 -net 3000 -addr 3000.20 -zone "1033" + lt0 -seed -phase 1 -net 1000 -addr 1000.50 -zone "1033" + +* For multiple LocalTalk cards, and an Ethernet card. + +* Order seems to matter here, Ethernet last:: + + lt0 -seed -phase 1 -net 1000 -addr 1000.10 -zone "LocalTalk1" + lt1 -seed -phase 1 -net 2000 -addr 2000.20 -zone "LocalTalk2" + eth0 -seed -phase 2 -net 3000 -addr 3000.30 -zone "EtherTalk" diff --git a/Documentation/networking/cops.txt b/Documentation/networking/cops.txt deleted file mode 100644 index 3e344b448e07..000000000000 --- a/Documentation/networking/cops.txt +++ /dev/null @@ -1,63 +0,0 @@ -Text File for the COPS LocalTalk Linux driver (cops.c). - By Jay Schulist - -This driver has two modes and they are: Dayna mode and Tangent mode. -Each mode corresponds with the type of card. It has been found -that there are 2 main types of cards and all other cards are -the same and just have different names or only have minor differences -such as more IO ports. As this driver is tested it will -become more clear exactly what cards are supported. - -Right now these cards are known to work with the COPS driver. The -LT-200 cards work in a somewhat more limited capacity than the -DL200 cards, which work very well and are in use by many people. - -TANGENT driver mode: - Tangent ATB-II, Novell NL-1000, Daystar Digital LT-200 -DAYNA driver mode: - Dayna DL2000/DaynaTalk PC (Half Length), COPS LT-95, - Farallon PhoneNET PC III, Farallon PhoneNET PC II -Other cards possibly supported mode unknown though: - Dayna DL2000 (Full length) - -The COPS driver defaults to using Dayna mode. To change the driver's -mode if you built a driver with dual support use board_type=1 or -board_type=2 for Dayna or Tangent with insmod. - -** Operation/loading of the driver. -Use modprobe like this: /sbin/modprobe cops.o (IO #) (IRQ #) -If you do not specify any options the driver will try and use the IO = 0x240, -IRQ = 5. As of right now I would only use IRQ 5 for the card, if autoprobing. - -To load multiple COPS driver Localtalk cards you can do one of the following. - -insmod cops io=0x240 irq=5 -insmod -o cops2 cops io=0x260 irq=3 - -Or in lilo.conf put something like this: - append="ether=5,0x240,lt0 ether=3,0x260,lt1" - -Then bring up the interface with ifconfig. It will look something like this: -lt0 Link encap:UNSPEC HWaddr 00-00-00-00-00-00-00-F7-00-00-00-00-00-00-00-00 - inet addr:192.168.1.2 Bcast:192.168.1.255 Mask:255.255.255.0 - UP BROADCAST RUNNING NOARP MULTICAST MTU:600 Metric:1 - RX packets:0 errors:0 dropped:0 overruns:0 frame:0 - TX packets:0 errors:0 dropped:0 overruns:0 carrier:0 coll:0 - -** Netatalk Configuration -You will need to configure atalkd with something like the following to make -it work with the cops.c driver. - -* For single LTalk card use. -dummy -seed -phase 2 -net 2000 -addr 2000.10 -zone "1033" -lt0 -seed -phase 1 -net 1000 -addr 1000.50 -zone "1033" - -* For multiple cards, Ethernet and LocalTalk. -eth0 -seed -phase 2 -net 3000 -addr 3000.20 -zone "1033" -lt0 -seed -phase 1 -net 1000 -addr 1000.50 -zone "1033" - -* For multiple LocalTalk cards, and an Ethernet card. -* Order seems to matter here, Ethernet last. -lt0 -seed -phase 1 -net 1000 -addr 1000.10 -zone "LocalTalk1" -lt1 -seed -phase 1 -net 2000 -addr 2000.20 -zone "LocalTalk2" -eth0 -seed -phase 2 -net 3000 -addr 3000.30 -zone "EtherTalk" diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst index 55802abd65a0..7b596810d479 100644 --- a/Documentation/networking/index.rst +++ b/Documentation/networking/index.rst @@ -46,6 +46,7 @@ Contents: baycom bonding cdc_mbim + cops .. only:: subproject and html diff --git a/drivers/net/appletalk/Kconfig b/drivers/net/appletalk/Kconfig index af509b05ac5c..d4e51c048f62 100644 --- a/drivers/net/appletalk/Kconfig +++ b/drivers/net/appletalk/Kconfig @@ -59,7 +59,7 @@ config COPS package. This driver is experimental, which means that it may not work. This driver will only work if you choose "AppleTalk DDP" networking support, above. - Please read the file . + Please read the file . config COPS_DAYNA bool "Dayna firmware support" From patchwork Mon Apr 27 22:01:27 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Mauro Carvalho Chehab X-Patchwork-Id: 220442 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-10.1 required=3.0 tests=DKIMWL_WL_HIGH, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, INCLUDES_PATCH, MAILING_LIST_MULTI, SIGNED_OFF_BY, SPF_HELO_NONE,SPF_PASS,USER_AGENT_GIT autolearn=unavailable autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 6E240C82A00 for ; Mon, 27 Apr 2020 22:05:43 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 4981A2087E for ; Mon, 27 Apr 2020 22:05:43 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1588025143; bh=Emi2yoocs4hV5xnVSqpHUmvmCGjZo8W2zvoib32QGkI=; h=From:To:Cc:Subject:Date:In-Reply-To:References:List-ID:From; b=o5hz+wOBmEkVf2xDlxy33OqxhL2LuTSYFegNtGQYG245gTCyhbDx3RH40cEdZvHFR Okrdn4Gzc39jrTOqkhqBHBn5qY8hwy64iVhuioxNSOabs+DFpubd1d8JGsDUmAM4mU g74udQLIONX1Np9Hscc36y58oz1ObprBjIylo9Jw= Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1727000AbgD0WFe (ORCPT ); Mon, 27 Apr 2020 18:05:34 -0400 Received: from mail.kernel.org ([198.145.29.99]:48008 "EHLO mail.kernel.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726309AbgD0WB6 (ORCPT ); Mon, 27 Apr 2020 18:01:58 -0400 Received: from mail.kernel.org (ip5f5ad5c5.dynamic.kabel-deutschland.de [95.90.213.197]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPSA id 828DC21BE5; Mon, 27 Apr 2020 22:01:56 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1588024916; bh=Emi2yoocs4hV5xnVSqpHUmvmCGjZo8W2zvoib32QGkI=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=K/3QhxJ9FaZVq+QqESOYha1vU32VTfaKA8teo8JxjeKSYPFASAftlZc+VVowzVgPt CJoYwRfxE3eq1WSbVGbqop8zzGgJBd8EvOxrvwPpZXIjNSQ9lnAByZxM0UlmcJbt1d X7WvDjD7N147NfVJAasRKjsAx5GzNGseJslQ8wKo= Received: from mchehab by mail.kernel.org with local (Exim 4.92.3) (envelope-from ) id 1jTBp4-000Iob-QQ; Tue, 28 Apr 2020 00:01:54 +0200 From: Mauro Carvalho Chehab To: Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Jonathan Corbet , "David S. Miller" , Jakub Kicinski , netdev@vger.kernel.org Subject: [PATCH 12/38] docs: networking: convert cxacru.txt to ReST Date: Tue, 28 Apr 2020 00:01:27 +0200 Message-Id: X-Mailer: git-send-email 2.25.4 In-Reply-To: References: MIME-Version: 1.0 Sender: netdev-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: netdev@vger.kernel.org - add SPDX header; - add a document title; - mark code blocks and literals as such; - mark lists as such; - adjust identation, whitespaces and blank lines; - add to networking/index.rst. Signed-off-by: Mauro Carvalho Chehab --- .../networking/{cxacru.txt => cxacru.rst} | 86 ++++++++++++------- Documentation/networking/index.rst | 1 + 2 files changed, 54 insertions(+), 33 deletions(-) rename Documentation/networking/{cxacru.txt => cxacru.rst} (66%) diff --git a/Documentation/networking/cxacru.txt b/Documentation/networking/cxacru.rst similarity index 66% rename from Documentation/networking/cxacru.txt rename to Documentation/networking/cxacru.rst index 2cce04457b4d..6088af2ffeda 100644 --- a/Documentation/networking/cxacru.txt +++ b/Documentation/networking/cxacru.rst @@ -1,3 +1,9 @@ +.. SPDX-License-Identifier: GPL-2.0 + +======================== +ATM cxacru device driver +======================== + Firmware is required for this device: http://accessrunner.sourceforge.net/ While it is capable of managing/maintaining the ADSL connection without the @@ -19,29 +25,35 @@ several sysfs attribute files for retrieving device statistics: * adsl_headend * adsl_headend_environment - Information about the remote headend. + + - Information about the remote headend. * adsl_config - Configuration writing interface. - Write parameters in hexadecimal format =, - separated by whitespace, e.g.: + + - Configuration writing interface. + - Write parameters in hexadecimal format =, + separated by whitespace, e.g.: + "1=0 a=5" - Up to 7 parameters at a time will be sent and the modem will restart - the ADSL connection when any value is set. These are logged for future - reference. + + - Up to 7 parameters at a time will be sent and the modem will restart + the ADSL connection when any value is set. These are logged for future + reference. * downstream_attenuation (dB) * downstream_bits_per_frame * downstream_rate (kbps) * downstream_snr_margin (dB) - Downstream stats. + + - Downstream stats. * upstream_attenuation (dB) * upstream_bits_per_frame * upstream_rate (kbps) * upstream_snr_margin (dB) * transmitter_power (dBm/Hz) - Upstream stats. + + - Upstream stats. * downstream_crc_errors * downstream_fec_errors @@ -49,48 +61,56 @@ several sysfs attribute files for retrieving device statistics: * upstream_crc_errors * upstream_fec_errors * upstream_hec_errors - Error counts. + + - Error counts. * line_startable - Indicates that ADSL support on the device - is/can be enabled, see adsl_start. + + - Indicates that ADSL support on the device + is/can be enabled, see adsl_start. * line_status - "initialising" - "down" - "attempting to activate" - "training" - "channel analysis" - "exchange" - "waiting" - "up" + + - "initialising" + - "down" + - "attempting to activate" + - "training" + - "channel analysis" + - "exchange" + - "waiting" + - "up" Changes between "down" and "attempting to activate" if there is no signal. * link_status - "not connected" - "connected" - "lost" + + - "not connected" + - "connected" + - "lost" * mac_address * modulation - "" (when not connected) - "ANSI T1.413" - "ITU-T G.992.1 (G.DMT)" - "ITU-T G.992.2 (G.LITE)" + + - "" (when not connected) + - "ANSI T1.413" + - "ITU-T G.992.1 (G.DMT)" + - "ITU-T G.992.2 (G.LITE)" * startup_attempts - Count of total attempts to initialise ADSL. + + - Count of total attempts to initialise ADSL. To enable/disable ADSL, the following can be written to the adsl_state file: - "start" - "stop - "restart" (stops, waits 1.5s, then starts) - "poll" (used to resume status polling if it was disabled due to failure) -Changes in adsl/line state are reported via kernel log messages: + - "start" + - "stop + - "restart" (stops, waits 1.5s, then starts) + - "poll" (used to resume status polling if it was disabled due to failure) + +Changes in adsl/line state are reported via kernel log messages:: + [4942145.150704] ATM dev 0: ADSL state: running [4942243.663766] ATM dev 0: ADSL line: down [4942249.665075] ATM dev 0: ADSL line: attempting to activate diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst index 7b596810d479..4c8e896490e0 100644 --- a/Documentation/networking/index.rst +++ b/Documentation/networking/index.rst @@ -47,6 +47,7 @@ Contents: bonding cdc_mbim cops + cxacru .. only:: subproject and html From patchwork Mon Apr 27 22:01:28 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Mauro Carvalho Chehab X-Patchwork-Id: 220441 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-10.1 required=3.0 tests=DKIMWL_WL_HIGH, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, INCLUDES_PATCH, MAILING_LIST_MULTI, SIGNED_OFF_BY, SPF_HELO_NONE,SPF_PASS,USER_AGENT_GIT autolearn=unavailable autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 6321FC82A02 for ; Mon, 27 Apr 2020 22:05:49 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 3E4EE2087E for ; Mon, 27 Apr 2020 22:05:49 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1588025149; bh=Ez5DysS12alFSCGzxD+JpDgKPRZigXc7wY6pgLEfTlQ=; h=From:To:Cc:Subject:Date:In-Reply-To:References:List-ID:From; b=Jig4skgggd8QLDybA2OFFDo+27MRQGUnuVPU0jo8gZCWntiDlOHlhhxW05yTJrBlR GoHd9ZG6F9zmHfDtKpvFvkDmh2xZqzrmNJKO/Wr2Jb/DlCTuWf3it+2hLbx3q+sdQZ trYa++QyVUiv+9E6Qevk5uzIHwm2TS0OUzJS7Ggk= Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1727024AbgD0WFq (ORCPT ); Mon, 27 Apr 2020 18:05:46 -0400 Received: from mail.kernel.org ([198.145.29.99]:48022 "EHLO mail.kernel.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726329AbgD0WB6 (ORCPT ); Mon, 27 Apr 2020 18:01:58 -0400 Received: from mail.kernel.org (ip5f5ad5c5.dynamic.kabel-deutschland.de [95.90.213.197]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPSA id 8E02E21D7D; Mon, 27 Apr 2020 22:01:56 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1588024916; bh=Ez5DysS12alFSCGzxD+JpDgKPRZigXc7wY6pgLEfTlQ=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=CPnP3dWy1rVmzBOc+lQzDyQS50F7Kr8HaGt1qx6TPlk40VJUMvaDucCAkdt7IhepB H0BBr9on6dGvbh1b6FWqIJX5tq0gg1JC7le8QYprw5abQjy5npiQWG1VfaLjcdRKRA QZsYsIrY2ZSw25mA/AbBkPjjF2dP0z5hWGkyl76Q= Received: from mchehab by mail.kernel.org with local (Exim 4.92.3) (envelope-from ) id 1jTBp4-000Iog-Rj; Tue, 28 Apr 2020 00:01:54 +0200 From: Mauro Carvalho Chehab To: Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Jonathan Corbet , "David S. Miller" , Jakub Kicinski , netdev@vger.kernel.org Subject: [PATCH 13/38] docs: networking: convert dccp.txt to ReST Date: Tue, 28 Apr 2020 00:01:28 +0200 Message-Id: <0dc5f31ae8ddf18a57d9f9d2922af3a09e0f357b.1588024424.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.25.4 In-Reply-To: References: MIME-Version: 1.0 Sender: netdev-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: netdev@vger.kernel.org - add SPDX header; - adjust title markup; - comment out text-only TOC from html/pdf output; - mark code blocks and literals as such; - adjust identation, whitespaces and blank lines; - add to networking/index.rst. Signed-off-by: Mauro Carvalho Chehab --- .../networking/{dccp.txt => dccp.rst} | 39 ++++++++++++------- Documentation/networking/index.rst | 1 + 2 files changed, 25 insertions(+), 15 deletions(-) rename Documentation/networking/{dccp.txt => dccp.rst} (94%) diff --git a/Documentation/networking/dccp.txt b/Documentation/networking/dccp.rst similarity index 94% rename from Documentation/networking/dccp.txt rename to Documentation/networking/dccp.rst index 55c575fcaf17..dde16be04456 100644 --- a/Documentation/networking/dccp.txt +++ b/Documentation/networking/dccp.rst @@ -1,16 +1,18 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============= DCCP protocol ============= -Contents -======== -- Introduction -- Missing features -- Socket options -- Sysctl variables -- IOCTLs -- Other tunables -- Notes +.. Contents + - Introduction + - Missing features + - Socket options + - Sysctl variables + - IOCTLs + - Other tunables + - Notes Introduction @@ -38,6 +40,7 @@ The Linux DCCP implementation does not currently support all the features that a specified in RFCs 4340...42. The known bugs are at: + http://www.linuxfoundation.org/collaborate/workgroups/networking/todo#DCCP For more up-to-date versions of the DCCP implementation, please consider using @@ -54,7 +57,8 @@ defined: the "simple" policy (DCCPQ_POLICY_SIMPLE), which does nothing special, and a priority-based variant (DCCPQ_POLICY_PRIO). The latter allows to pass an u32 priority value as ancillary data to sendmsg(), where higher numbers indicate a higher packet priority (similar to SO_PRIORITY). This ancillary data needs to -be formatted using a cmsg(3) message header filled in as follows: +be formatted using a cmsg(3) message header filled in as follows:: + cmsg->cmsg_level = SOL_DCCP; cmsg->cmsg_type = DCCP_SCM_PRIORITY; cmsg->cmsg_len = CMSG_LEN(sizeof(uint32_t)); /* or CMSG_LEN(4) */ @@ -94,7 +98,7 @@ must be registered on the socket before calling connect() or listen(). DCCP_SOCKOPT_TX_CCID is read/write. It returns the current CCID (if set) or sets the preference list for the TX CCID, using the same format as DCCP_SOCKOPT_CCID. -Please note that the getsockopt argument type here is `int', not uint8_t. +Please note that the getsockopt argument type here is ``int``, not uint8_t. DCCP_SOCKOPT_RX_CCID is analogous to DCCP_SOCKOPT_TX_CCID, but for the RX CCID. @@ -113,6 +117,7 @@ be enabled at the receiver, too with suitable choice of CsCov. DCCP_SOCKOPT_SEND_CSCOV sets the sender checksum coverage. Values in the range 0..15 are acceptable. The default setting is 0 (full coverage), values between 1..15 indicate partial coverage. + DCCP_SOCKOPT_RECV_CSCOV is for the receiver and has a different meaning: it sets a threshold, where again values 0..15 are acceptable. The default of 0 means that all packets with a partial coverage will be discarded. @@ -123,11 +128,13 @@ DCCP_SOCKOPT_RECV_CSCOV is for the receiver and has a different meaning: it The following two options apply to CCID 3 exclusively and are getsockopt()-only. In either case, a TFRC info struct (defined in ) is returned. + DCCP_SOCKOPT_CCID_RX_INFO - Returns a `struct tfrc_rx_info' in optval; the buffer for optval and + Returns a ``struct tfrc_rx_info`` in optval; the buffer for optval and optlen must be set to at least sizeof(struct tfrc_rx_info). + DCCP_SOCKOPT_CCID_TX_INFO - Returns a `struct tfrc_tx_info' in optval; the buffer for optval and + Returns a ``struct tfrc_tx_info`` in optval; the buffer for optval and optlen must be set to at least sizeof(struct tfrc_tx_info). On unidirectional connections it is useful to close the unused half-connection @@ -182,7 +189,7 @@ sync_ratelimit = 125 ms IOCTLS ====== FIONREAD - Works as in udp(7): returns in the `int' argument pointer the size of + Works as in udp(7): returns in the ``int`` argument pointer the size of the next pending datagram in bytes, or 0 when no datagram is pending. @@ -191,10 +198,12 @@ Other tunables Per-route rto_min support CCID-2 supports the RTAX_RTO_MIN per-route setting for the minimum value of the RTO timer. This setting can be modified via the 'rto_min' option - of iproute2; for example: + of iproute2; for example:: + > ip route change 10.0.0.0/24 rto_min 250j dev wlan0 > ip route add 10.0.0.254/32 rto_min 800j dev wlan0 > ip route show dev wlan0 + CCID-3 also supports the rto_min setting: it is used to define the lower bound for the expiry of the nofeedback timer. This can be useful on LANs with very low RTTs (e.g., loopback, Gbit ethernet). diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst index 4c8e896490e0..3894043332de 100644 --- a/Documentation/networking/index.rst +++ b/Documentation/networking/index.rst @@ -48,6 +48,7 @@ Contents: cdc_mbim cops cxacru + dccp .. only:: subproject and html From patchwork Mon Apr 27 22:01:30 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Mauro Carvalho Chehab X-Patchwork-Id: 220456 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-10.1 required=3.0 tests=DKIMWL_WL_HIGH, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, INCLUDES_PATCH, MAILING_LIST_MULTI, SIGNED_OFF_BY, SPF_HELO_NONE,SPF_PASS,USER_AGENT_GIT autolearn=unavailable autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 53552C82A05 for ; Mon, 27 Apr 2020 22:02:53 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 26172208FE for ; Mon, 27 Apr 2020 22:02:53 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1588024973; bh=kfeaxpOGbwlTZVDg0aWICkcxxb1d3iaKSlL4ED1+uBU=; h=From:To:Cc:Subject:Date:In-Reply-To:References:List-ID:From; b=DRJBvneaNB+PVEKHpdH/QbBnDMKz5UBwY6J6AY2stMcgae9a7oblP0QFhrcryd00M few1e8Cj3BRPa1ZcgA3jz+WOQAFtAVa0rCJzZVVxnZa48RpaDAN6PAm5wAtP0/Onv/ XMv6LY1DKhO7UGalha4HzTXkiHUGLq+j2sCsbraQ= Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1726436AbgD0WCC (ORCPT ); Mon, 27 Apr 2020 18:02:02 -0400 Received: from mail.kernel.org ([198.145.29.99]:48024 "EHLO mail.kernel.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726355AbgD0WCA (ORCPT ); Mon, 27 Apr 2020 18:02:00 -0400 Received: from mail.kernel.org (ip5f5ad5c5.dynamic.kabel-deutschland.de [95.90.213.197]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPSA id 9ABC721D91; Mon, 27 Apr 2020 22:01:56 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1588024916; bh=kfeaxpOGbwlTZVDg0aWICkcxxb1d3iaKSlL4ED1+uBU=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=bCfLx/mg+fsWsOPPtIVTBifEQUg6DOuylhQon+XrGzlCJ05q1Ndy0tOs/jd+IB3iG 5FPqPGMMcoKrYXxY36oDkU9YHa4hPVAfR07m4a/Ms0H5OcjhPwk/e4LzqHw2nhm/gK kZKJDI8oBvDKTrIHuZNETKcpL76dI/7RLSZz7tsY= Received: from mchehab by mail.kernel.org with local (Exim 4.92.3) (envelope-from ) id 1jTBp4-000Ioq-TK; Tue, 28 Apr 2020 00:01:54 +0200 From: Mauro Carvalho Chehab To: Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Jonathan Corbet , "David S. Miller" , Jakub Kicinski , linux-decnet-user@lists.sourceforge.net, netdev@vger.kernel.org Subject: [PATCH 15/38] docs: networking: convert decnet.txt to ReST Date: Tue, 28 Apr 2020 00:01:30 +0200 Message-Id: <1dcd53e2396aabbb8b32e038113c13f9d77f9365.1588024424.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.25.4 In-Reply-To: References: MIME-Version: 1.0 Sender: netdev-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: netdev@vger.kernel.org - add SPDX header; - adjust titles and chapters, adding proper markups; - mark lists as such; - mark code blocks and literals as such; - adjust identation, whitespaces and blank lines; - add to networking/index.rst. Signed-off-by: Mauro Carvalho Chehab --- .../admin-guide/kernel-parameters.txt | 2 +- .../networking/{decnet.txt => decnet.rst} | 77 +++++++++++-------- Documentation/networking/index.rst | 1 + MAINTAINERS | 2 +- net/decnet/Kconfig | 4 +- 5 files changed, 50 insertions(+), 36 deletions(-) rename Documentation/networking/{decnet.txt => decnet.rst} (87%) diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt index 942e7f59a356..cd68635370c6 100644 --- a/Documentation/admin-guide/kernel-parameters.txt +++ b/Documentation/admin-guide/kernel-parameters.txt @@ -831,7 +831,7 @@ decnet.addr= [HW,NET] Format: [,] - See also Documentation/networking/decnet.txt. + See also Documentation/networking/decnet.rst. default_hugepagesz= [HW] The size of the default HugeTLB page. This is diff --git a/Documentation/networking/decnet.txt b/Documentation/networking/decnet.rst similarity index 87% rename from Documentation/networking/decnet.txt rename to Documentation/networking/decnet.rst index d192f8b9948b..b8bc11ff8370 100644 --- a/Documentation/networking/decnet.txt +++ b/Documentation/networking/decnet.rst @@ -1,26 +1,31 @@ - Linux DECnet Networking Layer Information - =========================================== +.. SPDX-License-Identifier: GPL-2.0 -1) Other documentation.... +========================================= +Linux DECnet Networking Layer Information +========================================= - o Project Home Pages - http://www.chygwyn.com/ - Kernel info - http://linux-decnet.sourceforge.net/ - Userland tools - http://www.sourceforge.net/projects/linux-decnet/ - Status page +1. Other documentation.... +========================== -2) Configuring the kernel + - Project Home Pages + - http://www.chygwyn.com/ - Kernel info + - http://linux-decnet.sourceforge.net/ - Userland tools + - http://www.sourceforge.net/projects/linux-decnet/ - Status page + +2. Configuring the kernel +========================= Be sure to turn on the following options: - CONFIG_DECNET (obviously) - CONFIG_PROC_FS (to see what's going on) - CONFIG_SYSCTL (for easy configuration) + - CONFIG_DECNET (obviously) + - CONFIG_PROC_FS (to see what's going on) + - CONFIG_SYSCTL (for easy configuration) if you want to try out router support (not properly debugged yet) you'll need the following options as well... - CONFIG_DECNET_ROUTER (to be able to add/delete routes) - CONFIG_NETFILTER (will be required for the DECnet routing daemon) + - CONFIG_DECNET_ROUTER (to be able to add/delete routes) + - CONFIG_NETFILTER (will be required for the DECnet routing daemon) Don't turn on SIOCGIFCONF support for DECnet unless you are really sure that you need it, in general you won't and it can cause ifconfig to @@ -29,7 +34,7 @@ malfunction. Run time configuration has changed slightly from the 2.4 system. If you want to configure an endnode, then the simplified procedure is as follows: - o Set the MAC address on your ethernet card before starting _any_ other + - Set the MAC address on your ethernet card before starting _any_ other network protocols. As soon as your network card is brought into the UP state, DECnet should @@ -37,7 +42,8 @@ start working. If you need something more complicated or are unsure how to set the MAC address, see the next section. Also all configurations which worked with 2.4 will work under 2.5 with no change. -3) Command line options +3. Command line options +======================= You can set a DECnet address on the kernel command line for compatibility with the 2.4 configuration procedure, but in general it's not needed any more. @@ -56,7 +62,7 @@ interface then you won't see any entries in /proc/net/neigh for the local host until such time as you start a connection. This doesn't affect the operation of the local communications in any other way though. -The kernel command line takes options looking like the following: +The kernel command line takes options looking like the following:: decnet.addr=1,2 @@ -82,7 +88,7 @@ address of the node in order for it to be autoconfigured (and then appear in FTP sites called dn2ethaddr which can compute the correct ethernet address to use. The address can be set by ifconfig either before or at the time the device is brought up. If you are using RedHat you can -add the line: +add the line:: MACADDR=AA:00:04:00:03:04 @@ -95,7 +101,7 @@ verify with iproute2). The default device for routing can be set through the /proc filesystem by setting /proc/sys/net/decnet/default_device to the device you want DECnet to route packets out of when no specific route -is available. Usually this will be eth0, for example: +is available. Usually this will be eth0, for example:: echo -n "eth0" >/proc/sys/net/decnet/default_device @@ -106,7 +112,9 @@ confirm that by looking in the default_device file of course. There is a list of what the other files under /proc/sys/net/decnet/ do on the kernel patch web site (shown above). -4) Run time kernel configuration +4. Run time kernel configuration +================================ + This is either done through the sysctl/proc interface (see the kernel web pages for details on what the various options do) or through the iproute2 @@ -122,20 +130,21 @@ since its the _only_ way to add and delete routes currently. Eventually there will be a routing daemon to send and receive routing messages for each interface and update the kernel routing tables accordingly. The routing daemon will use netfilter to listen to routing packets, and -rtnetlink to update the kernels routing tables. +rtnetlink to update the kernels routing tables. The DECnet raw socket layer has been removed since it was there purely for use by the routing daemon which will now use netfilter (a much cleaner and more generic solution) instead. -5) How can I tell if its working ? +5. How can I tell if its working? +================================= Here is a quick guide of what to look for in order to know if your DECnet kernel subsystem is working. - Is the node address set (see /proc/sys/net/decnet/node_address) - - Is the node of the correct type - (see /proc/sys/net/decnet/conf//forwarding) + - Is the node of the correct type + (see /proc/sys/net/decnet/conf//forwarding) - Is the Ethernet MAC address of each Ethernet card set to match the DECnet address. If in doubt use the dn2ethaddr utility available at the ftp archive. @@ -160,7 +169,8 @@ kernel subsystem is working. network, and see if you can obtain the same results. - At this point you are on your own... :-) -6) How to send a bug report +6. How to send a bug report +=========================== If you've found a bug and want to report it, then there are several things you can do to help me work out exactly what it is that is wrong. Useful @@ -175,18 +185,19 @@ information (_most_ of which _is_ _essential_) includes: - How much data was being transferred ? - Was the network congested ? - How can the problem be reproduced ? - - Can you use tcpdump to get a trace ? (N.B. Most (all?) versions of + - Can you use tcpdump to get a trace ? (N.B. Most (all?) versions of tcpdump don't understand how to dump DECnet properly, so including the hex listing of the packet contents is _essential_, usually the -x flag. You may also need to increase the length grabbed with the -s flag. The -e flag also provides very useful information (ethernet MAC addresses)) -7) MAC FAQ +7. MAC FAQ +========== A quick FAQ on ethernet MAC addresses to explain how Linux and DECnet -interact and how to get the best performance from your hardware. +interact and how to get the best performance from your hardware. -Ethernet cards are designed to normally only pass received network frames +Ethernet cards are designed to normally only pass received network frames to a host computer when they are addressed to it, or to the broadcast address. Linux has an interface which allows the setting of extra addresses for @@ -197,8 +208,8 @@ significant processor time and bus bandwidth can be used up on a busy network (see the NAPI documentation for a longer explanation of these effects). -DECnet makes use of this interface to allow running DECnet on an ethernet -card which has already been configured using TCP/IP (presumably using the +DECnet makes use of this interface to allow running DECnet on an ethernet +card which has already been configured using TCP/IP (presumably using the built in MAC address of the card, as usual) and/or to allow multiple DECnet addresses on each physical interface. If you do this, be aware that if your ethernet card doesn't support perfect hashing in its MAC address filter @@ -210,7 +221,8 @@ to gain the best efficiency. Better still is to use a card which supports NAPI as well. -8) Mailing list +8. Mailing list +=============== If you are keen to get involved in development, or want to ask questions about configuration, or even just report bugs, then there is a mailing @@ -218,7 +230,8 @@ list that you can join, details are at: http://sourceforge.net/mail/?group_id=4993 -9) Legal Info +9. Legal Info +============= The Linux DECnet project team have placed their code under the GPL. The software is provided "as is" and without warranty express or implied. diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst index 9e83d3bda4e0..e17432492745 100644 --- a/Documentation/networking/index.rst +++ b/Documentation/networking/index.rst @@ -50,6 +50,7 @@ Contents: cxacru dccp dctcp + decnet .. only:: subproject and html diff --git a/MAINTAINERS b/MAINTAINERS index a1558eb34c45..f5214418cc19 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -4739,7 +4739,7 @@ DECnet NETWORK LAYER L: linux-decnet-user@lists.sourceforge.net S: Orphan W: http://linux-decnet.sourceforge.net -F: Documentation/networking/decnet.txt +F: Documentation/networking/decnet.rst F: net/decnet/ DECSTATION PLATFORM SUPPORT diff --git a/net/decnet/Kconfig b/net/decnet/Kconfig index 0935453ccfd5..8f98fb2f2ec9 100644 --- a/net/decnet/Kconfig +++ b/net/decnet/Kconfig @@ -15,7 +15,7 @@ config DECNET . More detailed documentation is available in - . + . Be sure to say Y to "/proc file system support" and "Sysctl support" below when using DECnet, since you will need sysctl support to aid @@ -40,4 +40,4 @@ config DECNET_ROUTER filtering" option will be required for the forthcoming routing daemon to work. - See for more information. + See for more information. From patchwork Mon Apr 27 22:01:31 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Mauro Carvalho Chehab X-Patchwork-Id: 220448 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-10.1 required=3.0 tests=DKIMWL_WL_HIGH, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, INCLUDES_PATCH, MAILING_LIST_MULTI, SIGNED_OFF_BY, SPF_HELO_NONE,SPF_PASS,USER_AGENT_GIT autolearn=unavailable autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 8EC6CC82A01 for ; Mon, 27 Apr 2020 22:04:27 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 5C8052087E for ; Mon, 27 Apr 2020 22:04:27 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1588025067; bh=gQlY14y91kcptdZNtY5zBKxsEhtdicdMmT1yCxkyPsI=; h=From:To:Cc:Subject:Date:In-Reply-To:References:List-ID:From; b=kUV4mLNlY3g/RpOFI/AuHyjAPGKNciqXm2QEgZTJ5fbXQcvN+gwM5aIW3zYtQc1uC exU1GedqK1qgyyBOXZEgafrPXDoaryi6i0FWT63vYtziMuvl42wnTnLxSRAcHEwnYn rZrp4OiPavmYAssLSoiFlokcteLQJ5DKHEpc5Xpg= Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1726910AbgD0WEZ (ORCPT ); Mon, 27 Apr 2020 18:04:25 -0400 Received: from mail.kernel.org ([198.145.29.99]:48022 "EHLO mail.kernel.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726359AbgD0WCA (ORCPT ); Mon, 27 Apr 2020 18:02:00 -0400 Received: from mail.kernel.org (ip5f5ad5c5.dynamic.kabel-deutschland.de [95.90.213.197]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPSA id 9AB5A21D90; Mon, 27 Apr 2020 22:01:56 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1588024916; bh=gQlY14y91kcptdZNtY5zBKxsEhtdicdMmT1yCxkyPsI=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=NX3b/iqrP/erbDp256UpJdo+WWLxBtlRLXYCRXJb9CzdkPZ0M90QlE4z+q6FUrnvY vtHDzAizyKpSAYMk9xG0UKVa6TA+rv5OfOwZocmZHsvSYjujOehCOrQc4oYwMwT5t3 l2zu5s0/lo2QCkuOziEJQepUj1h0HLgz5TlrxU3E= Received: from mchehab by mail.kernel.org with local (Exim 4.92.3) (envelope-from ) id 1jTBp4-000Iou-U5; Tue, 28 Apr 2020 00:01:54 +0200 From: Mauro Carvalho Chehab To: Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Jonathan Corbet , "David S. Miller" , Jakub Kicinski , netdev@vger.kernel.org Subject: [PATCH 16/38] docs: networking: convert defza.txt to ReST Date: Tue, 28 Apr 2020 00:01:31 +0200 Message-Id: X-Mailer: git-send-email 2.25.4 In-Reply-To: References: MIME-Version: 1.0 Sender: netdev-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: netdev@vger.kernel.org Not much to be done here: - add SPDX header; - add a document title; - use :field: markup for the version number; - add to networking/index.rst. Signed-off-by: Mauro Carvalho Chehab --- Documentation/networking/{defza.txt => defza.rst} | 8 +++++++- Documentation/networking/index.rst | 1 + 2 files changed, 8 insertions(+), 1 deletion(-) rename Documentation/networking/{defza.txt => defza.rst} (91%) diff --git a/Documentation/networking/defza.txt b/Documentation/networking/defza.rst similarity index 91% rename from Documentation/networking/defza.txt rename to Documentation/networking/defza.rst index 663e4a906751..73c2f793ea26 100644 --- a/Documentation/networking/defza.txt +++ b/Documentation/networking/defza.rst @@ -1,4 +1,10 @@ -Notes on the DEC FDDIcontroller 700 (DEFZA-xx) driver v.1.1.4. +.. SPDX-License-Identifier: GPL-2.0 + +===================================================== +Notes on the DEC FDDIcontroller 700 (DEFZA-xx) driver +===================================================== + +:Version: v.1.1.4 DEC FDDIcontroller 700 is DEC's first-generation TURBOchannel FDDI diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst index e17432492745..c893127004b9 100644 --- a/Documentation/networking/index.rst +++ b/Documentation/networking/index.rst @@ -51,6 +51,7 @@ Contents: dccp dctcp decnet + defza .. only:: subproject and html From patchwork Mon Apr 27 22:01:32 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Mauro Carvalho Chehab X-Patchwork-Id: 220447 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-10.1 required=3.0 tests=DKIMWL_WL_HIGH, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, INCLUDES_PATCH, MAILING_LIST_MULTI, SIGNED_OFF_BY, SPF_HELO_NONE,SPF_PASS,USER_AGENT_GIT autolearn=unavailable autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id B9D2BC82A03 for ; Mon, 27 Apr 2020 22:04:41 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 769C12087E for ; Mon, 27 Apr 2020 22:04:41 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1588025081; bh=aarcxQWdZt/n5HSYEjYUvaw9zZE/lyV3YlS/MBeup0c=; h=From:To:Cc:Subject:Date:In-Reply-To:References:List-ID:From; b=SXBmwrBertg7EahEMw+9ADK+avFVHF4//NCAiVNvD/jMk2wTuI+fswQ/4iiy5jnRv cmYS/klXrTlvZLGwDwG01WJzLrwb6ElnT49fUazcEFhaJi/M7yC4pJ/3dXb+Dt80zl 7WTzd3y/FWWWYlcO04RrGqjG2mcT03Q1BFE+KwCM= Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1726194AbgD0WEa (ORCPT ); Mon, 27 Apr 2020 18:04:30 -0400 Received: from mail.kernel.org ([198.145.29.99]:48008 "EHLO mail.kernel.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726357AbgD0WCA (ORCPT ); Mon, 27 Apr 2020 18:02:00 -0400 Received: from mail.kernel.org (ip5f5ad5c5.dynamic.kabel-deutschland.de [95.90.213.197]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPSA id 9FB6021D94; Mon, 27 Apr 2020 22:01:56 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1588024916; bh=aarcxQWdZt/n5HSYEjYUvaw9zZE/lyV3YlS/MBeup0c=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=OsIWeIzpY6JePcU8MVUFaefm+5TQhlHA2T/C2btSM5RSCVFW+QwQIzyfvHco5KK2K U7pdhfd3/h0SgsQ/EGLnZE6NkKwLT25GsxUcwgh9dgludO6YE+GwuS86P0CRaaAYc7 MlWQRgbNegEvCRC3pr9gE3Be8GXzqU8kecEMKsXA= Received: from mchehab by mail.kernel.org with local (Exim 4.92.3) (envelope-from ) id 1jTBp4-000Ioz-Ur; Tue, 28 Apr 2020 00:01:54 +0200 From: Mauro Carvalho Chehab To: Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Jonathan Corbet , "David S. Miller" , Jakub Kicinski , Ilya Dryomov , Jeff Layton , Sage Weil , netdev@vger.kernel.org, ceph-devel@vger.kernel.org Subject: [PATCH 17/38] docs: networking: convert dns_resolver.txt to ReST Date: Tue, 28 Apr 2020 00:01:32 +0200 Message-Id: <99fb4641432ac8b51e58bbcf93664e9efb19ec9f.1588024424.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.25.4 In-Reply-To: References: MIME-Version: 1.0 Sender: netdev-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: netdev@vger.kernel.org - add SPDX header; - adjust titles and chapters, adding proper markups; - comment out text-only TOC from html/pdf output; - mark code blocks and literals as such; - adjust identation, whitespaces and blank lines; - add to networking/index.rst. Signed-off-by: Mauro Carvalho Chehab --- .../{dns_resolver.txt => dns_resolver.rst} | 52 +++++++++---------- Documentation/networking/index.rst | 1 + net/ceph/Kconfig | 2 +- net/dns_resolver/Kconfig | 2 +- net/dns_resolver/dns_key.c | 2 +- net/dns_resolver/dns_query.c | 2 +- 6 files changed, 30 insertions(+), 31 deletions(-) rename Documentation/networking/{dns_resolver.txt => dns_resolver.rst} (89%) diff --git a/Documentation/networking/dns_resolver.txt b/Documentation/networking/dns_resolver.rst similarity index 89% rename from Documentation/networking/dns_resolver.txt rename to Documentation/networking/dns_resolver.rst index eaa8f9a6fd5d..add4d59a99a5 100644 --- a/Documentation/networking/dns_resolver.txt +++ b/Documentation/networking/dns_resolver.rst @@ -1,8 +1,10 @@ - =================== - DNS Resolver Module - =================== +.. SPDX-License-Identifier: GPL-2.0 -Contents: +=================== +DNS Resolver Module +=================== + +.. Contents: - Overview. - Compilation. @@ -12,8 +14,7 @@ Contents: - Debugging. -======== -OVERVIEW +Overview ======== The DNS resolver module provides a way for kernel services to make DNS queries @@ -33,50 +34,50 @@ It does not yet support the following AFS features: This code is extracted from the CIFS filesystem. -=========== -COMPILATION +Compilation =========== -The module should be enabled by turning on the kernel configuration options: +The module should be enabled by turning on the kernel configuration options:: CONFIG_DNS_RESOLVER - tristate "DNS Resolver support" -========== -SETTING UP +Setting up ========== To set up this facility, the /etc/request-key.conf file must be altered so that /sbin/request-key can appropriately direct the upcalls. For example, to handle basic dname to IPv4/IPv6 address resolution, the following line should be -added: +added:: + #OP TYPE DESC CO-INFO PROGRAM ARG1 ARG2 ARG3 ... #====== ============ ======= ======= ========================== create dns_resolver * * /usr/sbin/cifs.upcall %k To direct a query for query type 'foo', a line of the following should be added -before the more general line given above as the first match is the one taken. +before the more general line given above as the first match is the one taken:: create dns_resolver foo:* * /usr/sbin/dns.foo %k -===== -USAGE +Usage ===== To make use of this facility, one of the following functions that are -implemented in the module can be called after doing: +implemented in the module can be called after doing:: #include - (1) int dns_query(const char *type, const char *name, size_t namelen, - const char *options, char **_result, time_t *_expiry); + :: + + int dns_query(const char *type, const char *name, size_t namelen, + const char *options, char **_result, time_t *_expiry); This is the basic access function. It looks for a cached DNS query and if it doesn't find it, it upcalls to userspace to make a new DNS query, which may then be cached. The key description is constructed as a string of the - form: + form:: [:] @@ -107,16 +108,14 @@ This can be cleared by any process that has the CAP_SYS_ADMIN capability by the use of KEYCTL_KEYRING_CLEAR on the keyring ID. -=============================== -READING DNS KEYS FROM USERSPACE +Reading DNS Keys from Userspace =============================== Keys of dns_resolver type can be read from userspace using keyctl_read() or "keyctl read/print/pipe". -========= -MECHANISM +Mechanism ========= The dnsresolver module registers a key type called "dns_resolver". Keys of @@ -147,11 +146,10 @@ See for further information about request-key function. -========= -DEBUGGING +Debugging ========= Debugging messages can be turned on dynamically by writing a 1 into the -following file: +following file:: - /sys/module/dnsresolver/parameters/debug + /sys/module/dnsresolver/parameters/debug diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst index c893127004b9..55746038a7e9 100644 --- a/Documentation/networking/index.rst +++ b/Documentation/networking/index.rst @@ -52,6 +52,7 @@ Contents: dctcp decnet defza + dns_resolver .. only:: subproject and html diff --git a/net/ceph/Kconfig b/net/ceph/Kconfig index 2e8e6f904920..d7bec7adc267 100644 --- a/net/ceph/Kconfig +++ b/net/ceph/Kconfig @@ -39,6 +39,6 @@ config CEPH_LIB_USE_DNS_RESOLVER be resolved using the CONFIG_DNS_RESOLVER facility. For information on how to use CONFIG_DNS_RESOLVER consult - Documentation/networking/dns_resolver.txt + Documentation/networking/dns_resolver.rst If unsure, say N. diff --git a/net/dns_resolver/Kconfig b/net/dns_resolver/Kconfig index 0a1c2238b4bd..255df9b6e9e8 100644 --- a/net/dns_resolver/Kconfig +++ b/net/dns_resolver/Kconfig @@ -19,7 +19,7 @@ config DNS_RESOLVER SMB2 later. DNS Resolver is supported by the userspace upcall helper "/sbin/dns.resolver" via /etc/request-key.conf. - See for further + See for further information. To compile this as a module, choose M here: the module will be called diff --git a/net/dns_resolver/dns_key.c b/net/dns_resolver/dns_key.c index ad53eb31d40f..3aced951d5ab 100644 --- a/net/dns_resolver/dns_key.c +++ b/net/dns_resolver/dns_key.c @@ -1,6 +1,6 @@ /* Key type used to cache DNS lookups made by the kernel * - * See Documentation/networking/dns_resolver.txt + * See Documentation/networking/dns_resolver.rst * * Copyright (c) 2007 Igor Mammedov * Author(s): Igor Mammedov (niallain@gmail.com) diff --git a/net/dns_resolver/dns_query.c b/net/dns_resolver/dns_query.c index cab4e0df924f..82b084cc1cc6 100644 --- a/net/dns_resolver/dns_query.c +++ b/net/dns_resolver/dns_query.c @@ -1,7 +1,7 @@ /* Upcall routine, designed to work as a key type and working through * /sbin/request-key to contact userspace when handling DNS queries. * - * See Documentation/networking/dns_resolver.txt + * See Documentation/networking/dns_resolver.rst * * Copyright (c) 2007 Igor Mammedov * Author(s): Igor Mammedov (niallain@gmail.com) From patchwork Mon Apr 27 22:01:33 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Mauro Carvalho Chehab X-Patchwork-Id: 220446 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-10.1 required=3.0 tests=DKIMWL_WL_HIGH, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, INCLUDES_PATCH, MAILING_LIST_MULTI, SIGNED_OFF_BY, SPF_HELO_NONE,SPF_PASS,USER_AGENT_GIT autolearn=unavailable autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 31FC0C82A00 for ; Mon, 27 Apr 2020 22:04:51 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 1153120575 for ; Mon, 27 Apr 2020 22:04:51 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1588025091; bh=hcDugR9Ei2kcALB6m15r0N7fV4ifciWFKj04gGXvBuE=; h=From:To:Cc:Subject:Date:In-Reply-To:References:List-ID:From; b=Etk5Alb7TyFxTPd8JJoHEAdVm0Mk5ICvEWjPJzEenHG9o++X3oxOz87fBBdiFZw5U AQGpUTbMRiR/TwyV8CUIQRvCrlQMTvjEXau2220u01i5YLESmczqmYHdH+xQC2DFSW hlvads3droHyK7rGwhb1ZCGpGlMkQv7RtDPS/WdQ= Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1726878AbgD0WEU (ORCPT ); Mon, 27 Apr 2020 18:04:20 -0400 Received: from mail.kernel.org ([198.145.29.99]:48116 "EHLO mail.kernel.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726364AbgD0WCA (ORCPT ); Mon, 27 Apr 2020 18:02:00 -0400 Received: from mail.kernel.org (ip5f5ad5c5.dynamic.kabel-deutschland.de [95.90.213.197]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPSA id A9592221EB; Mon, 27 Apr 2020 22:01:56 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1588024916; bh=hcDugR9Ei2kcALB6m15r0N7fV4ifciWFKj04gGXvBuE=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=GT+gPG34hk517db2YxFh+lLtciGEjV4Brm67oo557BBaUwujTGGRlz3qC7HSuPKc0 zr8AArJQGboc0B9fbIvvTbjBN7oXaKYVnGUCvTqnQ1V/VLTZBrIiIHkG4kHpuxj8Kt Qh2ohmupTnfCLj3v9UQaFTTpQaZBDtUIJBoXXXFg= Received: from mchehab by mail.kernel.org with local (Exim 4.92.3) (envelope-from ) id 1jTBp4-000Ip4-Ve; Tue, 28 Apr 2020 00:01:54 +0200 From: Mauro Carvalho Chehab To: Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Jonathan Corbet , "David S. Miller" , Jakub Kicinski , netdev@vger.kernel.org Subject: [PATCH 18/38] docs: networking: convert driver.txt to ReST Date: Tue, 28 Apr 2020 00:01:33 +0200 Message-Id: <830fa106e7fa2584038838973e71fe63ff73cac7.1588024424.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.25.4 In-Reply-To: References: MIME-Version: 1.0 Sender: netdev-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: netdev@vger.kernel.org - add SPDX header; - add a document title; - mark code blocks and literals as such; - adjust identation, whitespaces and blank lines; - add to networking/index.rst. Signed-off-by: Mauro Carvalho Chehab --- .../networking/{driver.txt => driver.rst} | 22 +++++++++++-------- Documentation/networking/index.rst | 1 + 2 files changed, 14 insertions(+), 9 deletions(-) rename Documentation/networking/{driver.txt => driver.rst} (85%) diff --git a/Documentation/networking/driver.txt b/Documentation/networking/driver.rst similarity index 85% rename from Documentation/networking/driver.txt rename to Documentation/networking/driver.rst index da59e2884130..c8f59dbda46f 100644 --- a/Documentation/networking/driver.txt +++ b/Documentation/networking/driver.rst @@ -1,4 +1,8 @@ -Document about softnet driver issues +.. SPDX-License-Identifier: GPL-2.0 + +===================== +Softnet Driver Issues +===================== Transmit path guidelines: @@ -8,7 +12,7 @@ Transmit path guidelines: transmit function will become busy. Instead it must maintain the queue properly. For example, - for a driver implementing scatter-gather this means: + for a driver implementing scatter-gather this means:: static netdev_tx_t drv_hard_start_xmit(struct sk_buff *skb, struct net_device *dev) @@ -38,25 +42,25 @@ Transmit path guidelines: return NETDEV_TX_OK; } - And then at the end of your TX reclamation event handling: + And then at the end of your TX reclamation event handling:: if (netif_queue_stopped(dp->dev) && - TX_BUFFS_AVAIL(dp) > (MAX_SKB_FRAGS + 1)) + TX_BUFFS_AVAIL(dp) > (MAX_SKB_FRAGS + 1)) netif_wake_queue(dp->dev); - For a non-scatter-gather supporting card, the three tests simply become: + For a non-scatter-gather supporting card, the three tests simply become:: /* This is a hard error log it. */ if (TX_BUFFS_AVAIL(dp) <= 0) - and: + and:: if (TX_BUFFS_AVAIL(dp) == 0) - and: + and:: if (netif_queue_stopped(dp->dev) && - TX_BUFFS_AVAIL(dp) > 0) + TX_BUFFS_AVAIL(dp) > 0) netif_wake_queue(dp->dev); 2) An ndo_start_xmit method must not modify the shared parts of a @@ -86,7 +90,7 @@ Close/stop guidelines: 1) After the ndo_stop routine has been called, the hardware must not receive or transmit any data. All in flight packets must - be aborted. If necessary, poll or wait for completion of + be aborted. If necessary, poll or wait for completion of any reset commands. 2) The ndo_stop routine will be called by unregister_netdevice diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst index 55746038a7e9..313f66900bce 100644 --- a/Documentation/networking/index.rst +++ b/Documentation/networking/index.rst @@ -53,6 +53,7 @@ Contents: decnet defza dns_resolver + driver .. only:: subproject and html From patchwork Mon Apr 27 22:01:38 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Mauro Carvalho Chehab X-Patchwork-Id: 220449 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-10.1 required=3.0 tests=DKIMWL_WL_HIGH, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, INCLUDES_PATCH, MAILING_LIST_MULTI, SIGNED_OFF_BY, SPF_HELO_NONE,SPF_PASS,USER_AGENT_GIT autolearn=unavailable autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 1B707C82A02 for ; Mon, 27 Apr 2020 22:04:20 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id E6EF320575 for ; Mon, 27 Apr 2020 22:04:19 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1588025060; bh=gZ3kqaJAqPpuWPwp8rsvec84t06UEJWSiB9rwLxgwaA=; h=From:To:Cc:Subject:Date:In-Reply-To:References:List-ID:From; b=bsJFvPE7YieXegQpPVgWgYJr0715MHUblv6a7iBZNWQlIURwjNRr6UnHyXE2+9w0C 303zg+joX1+Uh2T4KlWVnssPK6mRGGF5KR8FZvJ6yczEJXpC2T4kr/J0tECG7jqs2Y TJCitmiQDW+QAF2pgMrlhkrCUu/TOa7wR4VWXjrc= Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1726861AbgD0WET (ORCPT ); Mon, 27 Apr 2020 18:04:19 -0400 Received: from mail.kernel.org ([198.145.29.99]:48126 "EHLO mail.kernel.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726366AbgD0WCA (ORCPT ); Mon, 27 Apr 2020 18:02:00 -0400 Received: from mail.kernel.org (ip5f5ad5c5.dynamic.kabel-deutschland.de [95.90.213.197]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPSA id C7BF022209; Mon, 27 Apr 2020 22:01:56 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1588024917; bh=gZ3kqaJAqPpuWPwp8rsvec84t06UEJWSiB9rwLxgwaA=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=KrtBuD4zHi/kjtU352oo8dk/rXifZwHC7QAq3KbdSRa3Ilr6GFgnWScEtB/mbwma9 fZCmuep0OhOS76Czi/RwS9zJE0PpFUEpNvcMeJVj8uz5aTmtW8bHMdBI7Km2HRJpH9 FsJDliIasM/Tp0zQGkxm8wdvxDp7VeriJ221pqj8= Received: from mchehab by mail.kernel.org with local (Exim 4.92.3) (envelope-from ) id 1jTBp5-000IpT-3U; Tue, 28 Apr 2020 00:01:55 +0200 From: Mauro Carvalho Chehab To: Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Jonathan Corbet , "David S. Miller" , Jakub Kicinski , netdev@vger.kernel.org Subject: [PATCH 23/38] docs: networking: convert framerelay.txt to ReST Date: Tue, 28 Apr 2020 00:01:38 +0200 Message-Id: X-Mailer: git-send-email 2.25.4 In-Reply-To: References: MIME-Version: 1.0 Sender: netdev-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: netdev@vger.kernel.org - add SPDX header; - add a document title; - adjust identation, whitespaces and blank lines; - add to networking/index.rst. Signed-off-by: Mauro Carvalho Chehab --- .../{framerelay.txt => framerelay.rst} | 21 ++++++++++++------- Documentation/networking/index.rst | 1 + drivers/net/wan/Kconfig | 4 ++-- 3 files changed, 16 insertions(+), 10 deletions(-) rename Documentation/networking/{framerelay.txt => framerelay.rst} (93%) diff --git a/Documentation/networking/framerelay.txt b/Documentation/networking/framerelay.rst similarity index 93% rename from Documentation/networking/framerelay.txt rename to Documentation/networking/framerelay.rst index 1a0b720440dd..6d904399ec6d 100644 --- a/Documentation/networking/framerelay.txt +++ b/Documentation/networking/framerelay.rst @@ -1,4 +1,10 @@ -Frame Relay (FR) support for linux is built into a two tiered system of device +.. SPDX-License-Identifier: GPL-2.0 + +================ +Frame Relay (FR) +================ + +Frame Relay (FR) support for linux is built into a two tiered system of device drivers. The upper layer implements RFC1490 FR specification, and uses the Data Link Connection Identifier (DLCI) as its hardware address. Usually these are assigned by your network supplier, they give you the number/numbers of @@ -7,18 +13,18 @@ the Virtual Connections (VC) assigned to you. Each DLCI is a point-to-point link between your machine and a remote one. As such, a separate device is needed to accommodate the routing. Within the net-tools archives is 'dlcicfg'. This program will communicate with the -base "DLCI" device, and create new net devices named 'dlci00', 'dlci01'... +base "DLCI" device, and create new net devices named 'dlci00', 'dlci01'... The configuration script will ask you how many DLCIs you need, as well as how many DLCIs you want to assign to each Frame Relay Access Device (FRAD). The DLCI uses a number of function calls to communicate with the FRAD, all -of which are stored in the FRAD's private data area. assoc/deassoc, +of which are stored in the FRAD's private data area. assoc/deassoc, activate/deactivate and dlci_config. The DLCI supplies a receive function to the FRAD to accept incoming packets. With this initial offering, only 1 FRAD driver is available. With many thanks -to Sangoma Technologies, David Mandelstam & Gene Kozin, the S502A, S502E & -S508 are supported. This driver is currently set up for only FR, but as +to Sangoma Technologies, David Mandelstam & Gene Kozin, the S502A, S502E & +S508 are supported. This driver is currently set up for only FR, but as Sangoma makes more firmware modules available, it can be updated to provide them as well. @@ -32,8 +38,7 @@ an initial configuration. Additional FRAD device drivers can be added as hardware is available. At this time, the dlcicfg and fradcfg programs have not been incorporated into -the net-tools distribution. They can be found at ftp.invlogic.com, in +the net-tools distribution. They can be found at ftp.invlogic.com, in /pub/linux. Note that with OS/2 FTPD, you end up in /pub by default, so just -use 'cd linux'. v0.10 is for use on pre-2.0.3 and earlier, v0.15 is for +use 'cd linux'. v0.10 is for use on pre-2.0.3 and earlier, v0.15 is for pre-2.0.4 and later. - diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst index b2fb8b907d68..4e225f1f7039 100644 --- a/Documentation/networking/index.rst +++ b/Documentation/networking/index.rst @@ -58,6 +58,7 @@ Contents: fib_trie filter fore200e + framerelay .. only:: subproject and html diff --git a/drivers/net/wan/Kconfig b/drivers/net/wan/Kconfig index dbc0e3f7a3e2..3e21726c36e8 100644 --- a/drivers/net/wan/Kconfig +++ b/drivers/net/wan/Kconfig @@ -336,7 +336,7 @@ config DLCI To use frame relay, you need supporting hardware (called FRAD) and certain programs from the net-tools package as explained in - . + . To compile this driver as a module, choose M here: the module will be called dlci. @@ -361,7 +361,7 @@ config SDLA These are multi-protocol cards, but only Frame Relay is supported by the driver at this time. Please read - . + . To compile this driver as a module, choose M here: the module will be called sdla. From patchwork Mon Apr 27 22:01:39 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Mauro Carvalho Chehab X-Patchwork-Id: 220450 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-10.1 required=3.0 tests=DKIMWL_WL_HIGH, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, INCLUDES_PATCH, MAILING_LIST_MULTI, SIGNED_OFF_BY, SPF_HELO_NONE, SPF_PASS, USER_AGENT_GIT autolearn=ham autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 16302C82A02 for ; Mon, 27 Apr 2020 22:04:05 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id E05FA20575 for ; Mon, 27 Apr 2020 22:04:04 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1588025045; bh=3ppIvIG2mo//4/u76SXHlEN0GqilsRg7Wy3lNHnVkGo=; h=From:To:Cc:Subject:Date:In-Reply-To:References:List-ID:From; b=aSZc10qy9iCQ7F/hFrA/ZNtqq09x8uP4JcmkKRoX3dPpGgaStyCLzeLscaZow/aLj zXjH/l8bakgHTkRmfhgOgHQNuCtV71RfSD3qt6sEH/n5evF1hGUCgEBX74CRAqTAuG vx3YWioUGQVxyDzHMHsOcLFfPXvK27iRjZKcuUT4= Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1726377AbgD0WEE (ORCPT ); Mon, 27 Apr 2020 18:04:04 -0400 Received: from mail.kernel.org ([198.145.29.99]:48128 "EHLO mail.kernel.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726369AbgD0WCA (ORCPT ); Mon, 27 Apr 2020 18:02:00 -0400 Received: from mail.kernel.org (ip5f5ad5c5.dynamic.kabel-deutschland.de [95.90.213.197]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPSA id D284D2222A; Mon, 27 Apr 2020 22:01:56 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1588024917; bh=3ppIvIG2mo//4/u76SXHlEN0GqilsRg7Wy3lNHnVkGo=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=YwCT3StNpTX1f4y5zEJHCOm+f+EPzi98T5bQ9NJC+t8ezMFf373h3/5QEKVNm20z0 5+5S/aBHrP/8RbHovWKi3JL5onjWbNfvaORTS7of+Ki2ivY5bl36DLdYCCNEkfvu5K LpOpSc7UTtXs6vbQzzzI/1E/2IEMKIgQKK42dfVk= Received: from mchehab by mail.kernel.org with local (Exim 4.92.3) (envelope-from ) id 1jTBp5-000IpX-4H; Tue, 28 Apr 2020 00:01:55 +0200 From: Mauro Carvalho Chehab To: Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Jonathan Corbet , "David S. Miller" , Jakub Kicinski , netdev@vger.kernel.org Subject: [PATCH 24/38] docs: networking: convert generic-hdlc.txt to ReST Date: Tue, 28 Apr 2020 00:01:39 +0200 Message-Id: X-Mailer: git-send-email 2.25.4 In-Reply-To: References: MIME-Version: 1.0 Sender: netdev-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: netdev@vger.kernel.org - add SPDX header; - adjust title markup; - mark code blocks and literals as such; - adjust identation, whitespaces and blank lines; - add to networking/index.rst. Signed-off-by: Mauro Carvalho Chehab --- .../{generic-hdlc.txt => generic-hdlc.rst} | 86 +++++++++++++------ Documentation/networking/index.rst | 1 + 2 files changed, 63 insertions(+), 24 deletions(-) rename Documentation/networking/{generic-hdlc.txt => generic-hdlc.rst} (75%) diff --git a/Documentation/networking/generic-hdlc.txt b/Documentation/networking/generic-hdlc.rst similarity index 75% rename from Documentation/networking/generic-hdlc.txt rename to Documentation/networking/generic-hdlc.rst index 4eb3cc40b702..1c3bb5cb98d4 100644 --- a/Documentation/networking/generic-hdlc.txt +++ b/Documentation/networking/generic-hdlc.rst @@ -1,14 +1,22 @@ +.. SPDX-License-Identifier: GPL-2.0 + +================== Generic HDLC layer +================== + Krzysztof Halasa Generic HDLC layer currently supports: + 1. Frame Relay (ANSI, CCITT, Cisco and no LMI) + - Normal (routed) and Ethernet-bridged (Ethernet device emulation) interfaces can share a single PVC. - ARP support (no InARP support in the kernel - there is an experimental InARP user-space daemon available on: http://www.kernel.org/pub/linux/utils/net/hdlc/). + 2. raw HDLC - either IP (IPv4) interface or Ethernet device emulation 3. Cisco HDLC 4. PPP @@ -24,19 +32,24 @@ with IEEE 802.1Q (VLANs) and 802.1D (Ethernet bridging). Make sure the hdlc.o and the hardware driver are loaded. It should create a number of "hdlc" (hdlc0 etc) network devices, one for each WAN port. You'll need the "sethdlc" utility, get it from: + http://www.kernel.org/pub/linux/utils/net/hdlc/ -Compile sethdlc.c utility: +Compile sethdlc.c utility:: + gcc -O2 -Wall -o sethdlc sethdlc.c + Make sure you're using a correct version of sethdlc for your kernel. Use sethdlc to set physical interface, clock rate, HDLC mode used, and add any required PVCs if using Frame Relay. -Usually you want something like: +Usually you want something like:: sethdlc hdlc0 clock int rate 128000 sethdlc hdlc0 cisco interval 10 timeout 25 -or + +or:: + sethdlc hdlc0 rs232 clock ext sethdlc hdlc0 fr lmi ansi sethdlc hdlc0 create 99 @@ -49,46 +62,63 @@ any IP address to it) before using pvc devices. Setting interface: -* v35 | rs232 | x21 | t1 | e1 - sets physical interface for a given port - if the card has software-selectable interfaces - loopback - activate hardware loopback (for testing only) -* clock ext - both RX clock and TX clock external -* clock int - both RX clock and TX clock internal -* clock txint - RX clock external, TX clock internal -* clock txfromrx - RX clock external, TX clock derived from RX clock -* rate - sets clock rate in bps (for "int" or "txint" clock only) +* v35 | rs232 | x21 | t1 | e1 + - sets physical interface for a given port + if the card has software-selectable interfaces + loopback + - activate hardware loopback (for testing only) +* clock ext + - both RX clock and TX clock external +* clock int + - both RX clock and TX clock internal +* clock txint + - RX clock external, TX clock internal +* clock txfromrx + - RX clock external, TX clock derived from RX clock +* rate + - sets clock rate in bps (for "int" or "txint" clock only) Setting protocol: * hdlc - sets raw HDLC (IP-only) mode + nrz / nrzi / fm-mark / fm-space / manchester - sets transmission code + no-parity / crc16 / crc16-pr0 (CRC16 with preset zeros) / crc32-itu + crc16-itu (CRC16 with ITU-T polynomial) / crc16-itu-pr0 - sets parity * hdlc-eth - Ethernet device emulation using HDLC. Parity and encoding as above. * cisco - sets Cisco HDLC mode (IP, IPv6 and IPX supported) + interval - time in seconds between keepalive packets + timeout - time in seconds after last received keepalive packet before - we assume the link is down + we assume the link is down * ppp - sets synchronous PPP mode * x25 - sets X.25 mode * fr - Frame Relay mode + lmi ansi / ccitt / cisco / none - LMI (link management) type + dce - Frame Relay DCE (network) side LMI instead of default DTE (user). + It has nothing to do with clocks! - t391 - link integrity verification polling timer (in seconds) - user - t392 - polling verification timer (in seconds) - network - n391 - full status polling counter - user - n392 - error threshold - both user and network - n393 - monitored events count - both user and network + + - t391 - link integrity verification polling timer (in seconds) - user + - t392 - polling verification timer (in seconds) - network + - n391 - full status polling counter - user + - n392 - error threshold - both user and network + - n393 - monitored events count - both user and network Frame-Relay only: + * create n | delete n - adds / deletes PVC interface with DLCI #n. Newly created interface will be named pvc0, pvc1 etc. @@ -101,26 +131,34 @@ Frame-Relay only: Board-specific issues --------------------- -n2.o and c101.o need parameters to work: +n2.o and c101.o need parameters to work:: insmod n2 hw=io,irq,ram,ports[:io,irq,...] -example: + +example:: + insmod n2 hw=0x300,10,0xD0000,01 -or +or:: + insmod c101 hw=irq,ram[:irq,...] -example: + +example:: + insmod c101 hw=9,0xdc000 -If built into the kernel, these drivers need kernel (command line) parameters: +If built into the kernel, these drivers need kernel (command line) parameters:: + n2.hw=io,irq,ram,ports:... -or + +or:: + c101.hw=irq,ram:... If you have a problem with N2, C101 or PLX200SYN card, you can issue the -"private" command to see port's packet descriptor rings (in kernel logs): +"private" command to see port's packet descriptor rings (in kernel logs):: sethdlc hdlc0 private diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst index 4e225f1f7039..d34824b27264 100644 --- a/Documentation/networking/index.rst +++ b/Documentation/networking/index.rst @@ -59,6 +59,7 @@ Contents: filter fore200e framerelay + generic-hdlc .. only:: subproject and html From patchwork Mon Apr 27 22:01:42 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Mauro Carvalho Chehab X-Patchwork-Id: 220451 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-15.1 required=3.0 tests=DKIMWL_WL_HIGH, DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,INCLUDES_PATCH,MAILING_LIST_MULTI, MENTIONS_GIT_HOSTING, SIGNED_OFF_BY, SPF_HELO_NONE, SPF_PASS, URIBL_BLOCKED, USER_AGENT_GIT autolearn=unavailable autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 2BFC0C82A02 for ; Mon, 27 Apr 2020 22:03:57 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 06FA82087E for ; Mon, 27 Apr 2020 22:03:57 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1588025037; bh=MIpKEbXSntTtK5lZR5Rer4SXA8vyJjpcHy/mKV6KGgc=; h=From:To:Cc:Subject:Date:In-Reply-To:References:List-ID:From; b=gQI2fN78fM9oWKXXcyE+513rwk46HCtXX5f0Ox6TMVlqkq7b6CM3BfbUKwidKGdAm 96b8szxEifJDSsg2VscJrQG7VR5BylaU70oXjhYdqhwyw+5tMtfYuvMTQgAB+fHWWX TVIG67Mg573jFdegnOlV+LuiLGF93HAVqYGLoO9M= Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1726799AbgD0WDw (ORCPT ); Mon, 27 Apr 2020 18:03:52 -0400 Received: from mail.kernel.org ([198.145.29.99]:47936 "EHLO mail.kernel.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726377AbgD0WCA (ORCPT ); Mon, 27 Apr 2020 18:02:00 -0400 Received: from mail.kernel.org (ip5f5ad5c5.dynamic.kabel-deutschland.de [95.90.213.197]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPSA id E2ECC22240; Mon, 27 Apr 2020 22:01:56 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1588024917; bh=MIpKEbXSntTtK5lZR5Rer4SXA8vyJjpcHy/mKV6KGgc=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=DmDKgTM8JRvUHsOcdre2pilaXJ65LFa5sa0JmZnZ8hpt4MLANc2i+yYm1GLYFXHVU BW8I27rfZiA9aITnSRn7PbdPVJ6s56uRGR5d30yn911mdNOvFhVCRw1kDXDpQW4d87 OQmgdZ49lJP3DjNVKUj9a/ErDEor8QLBVJRY9GGs= Received: from mchehab by mail.kernel.org with local (Exim 4.92.3) (envelope-from ) id 1jTBp5-000Ipn-6e; Tue, 28 Apr 2020 00:01:55 +0200 From: Mauro Carvalho Chehab To: Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Jonathan Corbet , "David S. Miller" , Jakub Kicinski , netdev@vger.kernel.org Subject: [PATCH 27/38] docs: networking: convert gtp.txt to ReST Date: Tue, 28 Apr 2020 00:01:42 +0200 Message-Id: X-Mailer: git-send-email 2.25.4 In-Reply-To: References: MIME-Version: 1.0 Sender: netdev-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: netdev@vger.kernel.org - add SPDX header; - adjust titles and chapters, adding proper markups; - add notes markups; - adjust identation, whitespaces and blank lines; - add to networking/index.rst. Signed-off-by: Mauro Carvalho Chehab --- Documentation/networking/{gtp.txt => gtp.rst} | 95 +++++++++++-------- Documentation/networking/index.rst | 1 + 2 files changed, 59 insertions(+), 37 deletions(-) rename Documentation/networking/{gtp.txt => gtp.rst} (79%) diff --git a/Documentation/networking/gtp.txt b/Documentation/networking/gtp.rst similarity index 79% rename from Documentation/networking/gtp.txt rename to Documentation/networking/gtp.rst index 6966bbec1ecb..1563fb94b289 100644 --- a/Documentation/networking/gtp.txt +++ b/Documentation/networking/gtp.rst @@ -1,12 +1,18 @@ +.. SPDX-License-Identifier: GPL-2.0 + +===================================== The Linux kernel GTP tunneling module -====================================================================== -Documentation by Harald Welte and - Andreas Schultz +===================================== + +Documentation by + Harald Welte and + Andreas Schultz In 'drivers/net/gtp.c' you are finding a kernel-level implementation of a GTP tunnel endpoint. -== What is GTP == +What is GTP +=========== GTP is the Generic Tunnel Protocol, which is a 3GPP protocol used for tunneling User-IP payload between a mobile station (phone, modem) @@ -41,7 +47,8 @@ publicly via the 3GPP website at http://www.3gpp.org/DynaReport/29060.htm A direct PDF link to v13.6.0 is provided for convenience below: http://www.etsi.org/deliver/etsi_ts/129000_129099/129060/13.06.00_60/ts_129060v130600p.pdf -== The Linux GTP tunnelling module == +The Linux GTP tunnelling module +=============================== The module implements the function of a tunnel endpoint, i.e. it is able to decapsulate tunneled IP packets in the uplink originated by @@ -70,7 +77,8 @@ Userspace :) The official homepage of the module is at https://osmocom.org/projects/linux-kernel-gtp-u/wiki -== Userspace Programs with Linux Kernel GTP-U support == +Userspace Programs with Linux Kernel GTP-U support +================================================== At the time of this writing, there are at least two Free Software implementations that implement GTP-C and can use the netlink interface @@ -82,7 +90,8 @@ to make use of the Linux kernel GTP-U support: * ergw (GGSN + P-GW in Erlang): https://github.com/travelping/ergw -== Userspace Library / Command Line Utilities == +Userspace Library / Command Line Utilities +========================================== There is a userspace library called 'libgtpnl' which is based on libmnl and which implements a C-language API towards the netlink @@ -90,7 +99,8 @@ interface provided by the Kernel GTP module: http://git.osmocom.org/libgtpnl/ -== Protocol Versions == +Protocol Versions +================= There are two different versions of GTP-U: v0 [GSM TS 09.60] and v1 [3GPP TS 29.281]. Both are implemented in the Kernel GTP module. @@ -105,7 +115,8 @@ doesn't implement GTP-C, we don't have to worry about this. It's the responsibility of the control plane implementation in userspace to implement that. -== IPv6 == +IPv6 +==== The 3GPP specifications indicate either IPv4 or IPv6 can be used both on the inner (user) IP layer, or on the outer (transport) layer. @@ -114,22 +125,25 @@ Unfortunately, the Kernel module currently supports IPv6 neither for the User IP payload, nor for the outer IP layer. Patches or other Contributions to fix this are most welcome! -== Mailing List == +Mailing List +============ -If yo have questions regarding how to use the Kernel GTP module from +If you have questions regarding how to use the Kernel GTP module from your own software, or want to contribute to the code, please use the osmocom-net-grps mailing list for related discussion. The list can be reached at osmocom-net-gprs@lists.osmocom.org and the mailman interface for managing your subscription is at https://lists.osmocom.org/mailman/listinfo/osmocom-net-gprs -== Issue Tracker == +Issue Tracker +============= The Osmocom project maintains an issue tracker for the Kernel GTP-U module at https://osmocom.org/projects/linux-kernel-gtp-u/issues -== History / Acknowledgements == +History / Acknowledgements +========================== The Module was originally created in 2012 by Harald Welte, but never completed. Pablo came in to finish the mess Harald left behind. But @@ -139,9 +153,11 @@ In 2015, Andreas Schultz came to the rescue and fixed lots more bugs, extended it with new features and finally pushed all of us to get it mainline, where it was merged in 4.7.0. -== Architectural Details == +Architectural Details +===================== -=== Local GTP-U entity and tunnel identification === +Local GTP-U entity and tunnel identification +-------------------------------------------- GTP-U uses UDP for transporting PDU's. The receiving UDP port is 2152 for GTPv1-U and 3386 for GTPv0-U. @@ -164,15 +180,15 @@ Therefore: destination IP and the tunnel endpoint id. The source IP and port have no meaning and can change at any time. -[3GPP TS 29.281] Section 4.3.0 defines this so: +[3GPP TS 29.281] Section 4.3.0 defines this so:: -> The TEID in the GTP-U header is used to de-multiplex traffic -> incoming from remote tunnel endpoints so that it is delivered to the -> User plane entities in a way that allows multiplexing of different -> users, different packet protocols and different QoS levels. -> Therefore no two remote GTP-U endpoints shall send traffic to a -> GTP-U protocol entity using the same TEID value except -> for data forwarding as part of mobility procedures. + The TEID in the GTP-U header is used to de-multiplex traffic + incoming from remote tunnel endpoints so that it is delivered to the + User plane entities in a way that allows multiplexing of different + users, different packet protocols and different QoS levels. + Therefore no two remote GTP-U endpoints shall send traffic to a + GTP-U protocol entity using the same TEID value except + for data forwarding as part of mobility procedures. The definition above only defines that two remote GTP-U endpoints *should not* send to the same TEID, it *does not* forbid or exclude @@ -183,7 +199,8 @@ multiple or unknown peers. Therefore, the receiving side identifies tunnels exclusively based on TEIDs, not based on the source IP! -== APN vs. Network Device == +APN vs. Network Device +====================== The GTP-U driver creates a Linux network device for each Gi/SGi interface. @@ -201,29 +218,33 @@ number of Gi/SGi interfaces implemented by a GGSN/P-GW. [3GPP TS 29.061] Section 11.3 makes it clear that the selection of a specific Gi/SGi interfaces is made through the Access Point Name -(APN): +(APN):: -> 2. each private network manages its own addressing. In general this -> will result in different private networks having overlapping -> address ranges. A logically separate connection (e.g. an IP in IP -> tunnel or layer 2 virtual circuit) is used between the GGSN/P-GW -> and each private network. -> -> In this case the IP address alone is not necessarily unique. The -> pair of values, Access Point Name (APN) and IPv4 address and/or -> IPv6 prefixes, is unique. + 2. each private network manages its own addressing. In general this + will result in different private networks having overlapping + address ranges. A logically separate connection (e.g. an IP in IP + tunnel or layer 2 virtual circuit) is used between the GGSN/P-GW + and each private network. + + In this case the IP address alone is not necessarily unique. The + pair of values, Access Point Name (APN) and IPv4 address and/or + IPv6 prefixes, is unique. In order to support the overlapping address range use case, each APN is mapped to a separate Gi/SGi interface (network device). -NOTE: The Access Point Name is purely a control plane (GTP-C) concept. -At the GTP-U level, only Tunnel Endpoint Identifiers are present in -GTP-U packets and network devices are known +.. note:: + + The Access Point Name is purely a control plane (GTP-C) concept. + At the GTP-U level, only Tunnel Endpoint Identifiers are present in + GTP-U packets and network devices are known Therefore for a given UE the mapping in IP to PDN network is: + * network device + MS IP -> Peer IP + Peer TEID, and from PDN to IP network: + * local GTP-U IP + TEID -> network device Furthermore, before a received T-PDU is injected into the network diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst index 33afbb67f3fa..b29a08d1f941 100644 --- a/Documentation/networking/index.rst +++ b/Documentation/networking/index.rst @@ -62,6 +62,7 @@ Contents: generic-hdlc generic_netlink gen_stats + gtp .. only:: subproject and html From patchwork Mon Apr 27 22:01:44 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Mauro Carvalho Chehab X-Patchwork-Id: 220452 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-10.1 required=3.0 tests=DKIMWL_WL_HIGH, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, INCLUDES_PATCH, MAILING_LIST_MULTI, SIGNED_OFF_BY, SPF_HELO_NONE,SPF_PASS,USER_AGENT_GIT autolearn=unavailable autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 85648C82A08 for ; Mon, 27 Apr 2020 22:03:39 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 593C12087E for ; Mon, 27 Apr 2020 22:03:39 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1588025019; bh=korjmdIz5+QmtD2eNR4t6gFNj/yVol8UzgK9BHlywlM=; h=From:To:Cc:Subject:Date:In-Reply-To:References:List-ID:From; b=j8dHzombbYr+XP0SvIU1zBxGccBY/YzdphhSzhv4fK0FP427MTrLV9lpLMGyL/a5l uyzxg7DIlFVXn15WiDrLW0NKm+OpFKOuxxnbQWUyR/OZl/7dnT2sRizRFTzWN9vAze p3SPjBKLpN0X7kHOB7u4cIDkFCvQiDmJirNbIRVo= Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1726756AbgD0WDi (ORCPT ); Mon, 27 Apr 2020 18:03:38 -0400 Received: from mail.kernel.org ([198.145.29.99]:47986 "EHLO mail.kernel.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726378AbgD0WCB (ORCPT ); Mon, 27 Apr 2020 18:02:01 -0400 Received: from mail.kernel.org (ip5f5ad5c5.dynamic.kabel-deutschland.de [95.90.213.197]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPSA id ED3B82224E; Mon, 27 Apr 2020 22:01:56 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1588024917; bh=korjmdIz5+QmtD2eNR4t6gFNj/yVol8UzgK9BHlywlM=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=qbz+/zx6OyRtWiJyqMAA3erBs+E7NpVNGzQ4D5sM5C1Nt4R6enZIRVOM2dCQUpM9b Pd01KgISFMgp+H2Z4Uc+ckTfflH+mj+fxG9XZtyM4PHzmBYxgLur3KkkfSElxbKTpf HvgUr7tDu7BR1jj1l03rc8JvNY0Lg8unvfZr2i5Y= Received: from mchehab by mail.kernel.org with local (Exim 4.92.3) (envelope-from ) id 1jTBp5-000Ipx-8C; Tue, 28 Apr 2020 00:01:55 +0200 From: Mauro Carvalho Chehab To: Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Jonathan Corbet , "David S. Miller" , Jakub Kicinski , netdev@vger.kernel.org Subject: [PATCH 29/38] docs: networking: convert ila.txt to ReST Date: Tue, 28 Apr 2020 00:01:44 +0200 Message-Id: <92d7e5c4989e8aa5630d30bc07463de3662084c5.1588024424.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.25.4 In-Reply-To: References: MIME-Version: 1.0 Sender: netdev-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: netdev@vger.kernel.org - add SPDX header; - adjust title markup; - mark code blocks and literals as such; - adjust identation, whitespaces and blank lines; - add to networking/index.rst. Signed-off-by: Mauro Carvalho Chehab --- Documentation/networking/{ila.txt => ila.rst} | 81 +++++++++++-------- Documentation/networking/index.rst | 1 + 2 files changed, 47 insertions(+), 35 deletions(-) rename Documentation/networking/{ila.txt => ila.rst} (82%) diff --git a/Documentation/networking/ila.txt b/Documentation/networking/ila.rst similarity index 82% rename from Documentation/networking/ila.txt rename to Documentation/networking/ila.rst index a17dac9dc915..5ac0a6270b17 100644 --- a/Documentation/networking/ila.txt +++ b/Documentation/networking/ila.rst @@ -1,4 +1,8 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=================================== Identifier Locator Addressing (ILA) +=================================== Introduction @@ -26,11 +30,13 @@ The ILA protocol is described in Internet-Draft draft-herbert-intarea-ila. ILA terminology =============== - - Identifier A number that identifies an addressable node in the network + - Identifier + A number that identifies an addressable node in the network independent of its location. ILA identifiers are sixty-four bit values. - - Locator A network prefix that routes to a physical host. Locators + - Locator + A network prefix that routes to a physical host. Locators provide the topological location of an addressed node. ILA locators are sixty-four bit prefixes. @@ -51,17 +57,20 @@ ILA terminology bits) and an identifier (low order sixty-four bits). ILA addresses are never visible to an application. - - ILA host An end host that is capable of performing ILA translations + - ILA host + An end host that is capable of performing ILA translations on transmit or receive. - - ILA router A network node that performs ILA translation and forwarding + - ILA router + A network node that performs ILA translation and forwarding of translated packets. - ILA forwarding cache A type of ILA router that only maintains a working set cache of mappings. - - ILA node A network node capable of performing ILA translations. This + - ILA node + A network node capable of performing ILA translations. This can be an ILA router, ILA forwarding cache, or ILA host. @@ -82,18 +91,18 @@ Configuration and datapath for these two points of deployment is somewhat different. The diagram below illustrates the flow of packets through ILA as well -as showing ILA hosts and routers. +as showing ILA hosts and routers:: +--------+ +--------+ | Host A +-+ +--->| Host B | | | | (2) ILA (') | | +--------+ | ...addressed.... ( ) +--------+ - V +---+--+ . packet . +---+--+ (_) + V +---+--+ . packet . +---+--+ (_) (1) SIR | | ILA |----->-------->---->| ILA | | (3) SIR addressed +->|router| . . |router|->-+ addressed packet +---+--+ . IPv6 . +---+--+ packet - / . Network . - / . . +--+-++--------+ + / . Network . + / . . +--+-++--------+ +--------+ / . . |ILA || Host | | Host +--+ . .- -|host|| | | | . . +--+-++--------+ @@ -173,7 +182,7 @@ ILA address, never a SIR address. In the simplest format the identifier types, C-bit, and checksum adjustment value are not present so an identifier is considered an -unstructured sixty-four bit value. +unstructured sixty-four bit value:: +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Identifier | @@ -184,7 +193,7 @@ unstructured sixty-four bit value. The checksum neutral adjustment may be configured to always be present using neutral-map-auto. In this case there is no C-bit, but the checksum adjustment is in the low order 16 bits. The identifier is -still sixty-four bits. +still sixty-four bits:: +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Identifier | @@ -193,7 +202,7 @@ still sixty-four bits. +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ The C-bit may used to explicitly indicate that checksum neutral -mapping has been applied to an ILA address. The format is: +mapping has been applied to an ILA address. The format is:: +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | |C| Identifier | @@ -204,7 +213,7 @@ mapping has been applied to an ILA address. The format is: The identifier type field may be present to indicate the identifier type. If it is not present then the type is inferred based on mapping configuration. The checksum neutral adjustment may automatically -used with the identifier type as illustrated below. +used with the identifier type as illustrated below:: +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Type| Identifier | @@ -213,7 +222,7 @@ used with the identifier type as illustrated below. +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ If the identifier type and the C-bit can be present simultaneously so -the identifier format would be: +the identifier format would be:: +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Type|C| Identifier | @@ -258,28 +267,30 @@ same meanings as described above. Some examples ============= -# Configure an ILA route that uses checksum neutral mapping as well -# as type field. Note that the type field is set in the SIR address -# (the 2000 implies type is 1 which is LUID). -ip route add 3333:0:0:1:2000:0:1:87/128 encap ila 2001:0:87:0 \ - csum-mode neutral-map ident-type use-format +:: -# Configure an ILA LWT route that uses auto checksum neutral mapping -# (no C-bit) and configure identifier type to be LUID so that the -# identifier type field will not be present. -ip route add 3333:0:0:1:2000:0:2:87/128 encap ila 2001:0:87:1 \ - csum-mode neutral-map-auto ident-type luid + # Configure an ILA route that uses checksum neutral mapping as well + # as type field. Note that the type field is set in the SIR address + # (the 2000 implies type is 1 which is LUID). + ip route add 3333:0:0:1:2000:0:1:87/128 encap ila 2001:0:87:0 \ + csum-mode neutral-map ident-type use-format -ila_xlat configuration + # Configure an ILA LWT route that uses auto checksum neutral mapping + # (no C-bit) and configure identifier type to be LUID so that the + # identifier type field will not be present. + ip route add 3333:0:0:1:2000:0:2:87/128 encap ila 2001:0:87:1 \ + csum-mode neutral-map-auto ident-type luid -# Configure an ILA to SIR mapping that matches a locator and overwrites -# it with a SIR address (3333:0:0:1 in this example). The C-bit and -# identifier field are used. -ip ila add loc_match 2001:0:119:0 loc 3333:0:0:1 \ - csum-mode neutral-map-auto ident-type use-format + ila_xlat configuration -# Configure an ILA to SIR mapping where checksum neutral is automatically -# set without the C-bit and the identifier type is configured to be LUID -# so that the identifier type field is not present. -ip ila add loc_match 2001:0:119:0 loc 3333:0:0:1 \ - csum-mode neutral-map-auto ident-type use-format + # Configure an ILA to SIR mapping that matches a locator and overwrites + # it with a SIR address (3333:0:0:1 in this example). The C-bit and + # identifier field are used. + ip ila add loc_match 2001:0:119:0 loc 3333:0:0:1 \ + csum-mode neutral-map-auto ident-type use-format + + # Configure an ILA to SIR mapping where checksum neutral is automatically + # set without the C-bit and the identifier type is configured to be LUID + # so that the identifier type field is not present. + ip ila add loc_match 2001:0:119:0 loc 3333:0:0:1 \ + csum-mode neutral-map-auto ident-type use-format diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst index 5a7889df1375..488971f6b650 100644 --- a/Documentation/networking/index.rst +++ b/Documentation/networking/index.rst @@ -64,6 +64,7 @@ Contents: gen_stats gtp hinic + ila .. only:: subproject and html From patchwork Mon Apr 27 22:01:47 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Mauro Carvalho Chehab X-Patchwork-Id: 220454 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-10.1 required=3.0 tests=DKIMWL_WL_HIGH, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, INCLUDES_PATCH, MAILING_LIST_MULTI, SIGNED_OFF_BY, SPF_HELO_NONE,SPF_PASS,USER_AGENT_GIT autolearn=unavailable autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id EE049C82A04 for ; Mon, 27 Apr 2020 22:03:17 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id B046F2087E for ; Mon, 27 Apr 2020 22:03:17 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1588024997; bh=kJ7nuAYrQepxscJcqa5SQk6Dcd37HnIqGWIDAJTKfpw=; h=From:To:Cc:Subject:Date:In-Reply-To:References:List-ID:From; b=U7CykTmFhc7GJozATQX7lEv/UlqiNZdISp6JsFRLVwpKX6RB43bsvednrJh+9huBq rbEOYz+cq9NsgwBnV9SFagc8DDBk7K+BVQQiXx0HGjXfUzlmQTJa0MGClOHqX3Th09 wGikOl5Ap00CwuYSIgr2/3BqKAk/ctrSO4pjERls= Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1726596AbgD0WC6 (ORCPT ); Mon, 27 Apr 2020 18:02:58 -0400 Received: from mail.kernel.org ([198.145.29.99]:48008 "EHLO mail.kernel.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726402AbgD0WCB (ORCPT ); Mon, 27 Apr 2020 18:02:01 -0400 Received: from mail.kernel.org (ip5f5ad5c5.dynamic.kabel-deutschland.de [95.90.213.197]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPSA id 0C36422260; Mon, 27 Apr 2020 22:01:57 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1588024917; bh=kJ7nuAYrQepxscJcqa5SQk6Dcd37HnIqGWIDAJTKfpw=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=gH4dZdqP4JH8eN/EKaY5mayoBo96wRGMENIur4REBUcoqPNCJ62mkllreq2pgGP+q O2FCjUFjvTkUvQG1qe/IrZ3FPPuB+ecsUlptPV/gG6sGqTBv5MVDRxyl/RVPzokQ1X 7xhURxSj6DMGUTWRjQtWtwLcfoY8dWjCWaSm77Kk= Received: from mchehab by mail.kernel.org with local (Exim 4.92.3) (envelope-from ) id 1jTBp5-000IqC-BA; Tue, 28 Apr 2020 00:01:55 +0200 From: Mauro Carvalho Chehab To: Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Jonathan Corbet , "David S. Miller" , Jakub Kicinski , Chas Williams <3chas3@gmail.com>, netdev@vger.kernel.org, linux-atm-general@lists.sourceforge.net Subject: [PATCH 32/38] docs: networking: convert iphase.txt to ReST Date: Tue, 28 Apr 2020 00:01:47 +0200 Message-Id: <76e3297787c9b642d8ffe54f98eb2a6d36ff6207.1588024424.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.25.4 In-Reply-To: References: MIME-Version: 1.0 Sender: netdev-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: netdev@vger.kernel.org - add SPDX header; - adjust title using the proper markup; - mark code blocks and literals as such; - mark tables as such; - mark lists as such; - adjust identation, whitespaces and blank lines; - add to networking/index.rst. Signed-off-by: Mauro Carvalho Chehab --- Documentation/networking/index.rst | 1 + .../networking/{iphase.txt => iphase.rst} | 185 +++++++++++------- drivers/atm/Kconfig | 2 +- 3 files changed, 112 insertions(+), 76 deletions(-) rename Documentation/networking/{iphase.txt => iphase.rst} (50%) diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst index f81aeb87aa28..505eaa41ca2b 100644 --- a/Documentation/networking/index.rst +++ b/Documentation/networking/index.rst @@ -67,6 +67,7 @@ Contents: ila ipddp ip_dynaddr + iphase .. only:: subproject and html diff --git a/Documentation/networking/iphase.txt b/Documentation/networking/iphase.rst similarity index 50% rename from Documentation/networking/iphase.txt rename to Documentation/networking/iphase.rst index 670b72f16585..92d9b757d75a 100644 --- a/Documentation/networking/iphase.txt +++ b/Documentation/networking/iphase.rst @@ -1,27 +1,35 @@ +.. SPDX-License-Identifier: GPL-2.0 + +================================== +ATM (i)Chip IA Linux Driver Source +================================== + + READ ME FISRT - READ ME FISRT - ATM (i)Chip IA Linux Driver Source -------------------------------------------------------------------------------- - Read This Before You Begin! + + Read This Before You Begin! + -------------------------------------------------------------------------------- Description ------------ +=========== -This is the README file for the Interphase PCI ATM (i)Chip IA Linux driver +This is the README file for the Interphase PCI ATM (i)Chip IA Linux driver source release. The features and limitations of this driver are as follows: + - A single VPI (VPI value of 0) is supported. - - Supports 4K VCs for the server board (with 512K control memory) and 1K + - Supports 4K VCs for the server board (with 512K control memory) and 1K VCs for the client board (with 128K control memory). - UBR, ABR and CBR service categories are supported. - - Only AAL5 is supported. - - Supports setting of PCR on the VCs. + - Only AAL5 is supported. + - Supports setting of PCR on the VCs. - Multiple adapters in a system are supported. - - All variants of Interphase ATM PCI (i)Chip adapter cards are supported, - including x575 (OC3, control memory 128K , 512K and packet memory 128K, - 512K and 1M), x525 (UTP25) and x531 (DS3 and E3). See + - All variants of Interphase ATM PCI (i)Chip adapter cards are supported, + including x575 (OC3, control memory 128K , 512K and packet memory 128K, + 512K and 1M), x525 (UTP25) and x531 (DS3 and E3). See http://www.iphase.com/ for details. - Only x86 platforms are supported. @@ -29,128 +37,155 @@ The features and limitations of this driver are as follows: Before You Start ----------------- +================ Installation ------------ 1. Installing the adapters in the system + To install the ATM adapters in the system, follow the steps below. + a. Login as root. b. Shut down the system and power off the system. c. Install one or more ATM adapters in the system. - d. Connect each adapter to a port on an ATM switch. The green 'Link' - LED on the front panel of the adapter will be on if the adapter is - connected to the switch properly when the system is powered up. + d. Connect each adapter to a port on an ATM switch. The green 'Link' + LED on the front panel of the adapter will be on if the adapter is + connected to the switch properly when the system is powered up. e. Power on and boot the system. 2. [ Removed ] 3. Rebuild kernel with ABR support + [ a. and b. removed ] - c. Reconfigure the kernel, choose the Interphase ia driver through "make + + c. Reconfigure the kernel, choose the Interphase ia driver through "make menuconfig" or "make xconfig". - d. Rebuild the kernel, loadable modules and the atm tools. + d. Rebuild the kernel, loadable modules and the atm tools. e. Install the new built kernel and modules and reboot. 4. Load the adapter hardware driver (ia driver) if it is built as a module + a. Login as root. b. Change directory to /lib/modules//atm. c. Run "insmod suni.o;insmod iphase.o" - The yellow 'status' LED on the front panel of the adapter will blink - while the driver is loaded in the system. - d. To verify that the 'ia' driver is loaded successfully, run the - following command: + The yellow 'status' LED on the front panel of the adapter will blink + while the driver is loaded in the system. + d. To verify that the 'ia' driver is loaded successfully, run the + following command:: - cat /proc/atm/devices + cat /proc/atm/devices - If the driver is loaded successfully, the output of the command will - be similar to the following lines: + If the driver is loaded successfully, the output of the command will + be similar to the following lines:: - Itf Type ESI/"MAC"addr AAL(TX,err,RX,err,drop) ... - 0 ia xxxxxxxxx 0 ( 0 0 0 0 0 ) 5 ( 0 0 0 0 0 ) + Itf Type ESI/"MAC"addr AAL(TX,err,RX,err,drop) ... + 0 ia xxxxxxxxx 0 ( 0 0 0 0 0 ) 5 ( 0 0 0 0 0 ) - You can also check the system log file /var/log/messages for messages - related to the ATM driver. + You can also check the system log file /var/log/messages for messages + related to the ATM driver. -5. Ia Driver Configuration +5. Ia Driver Configuration 5.1 Configuration of adapter buffers The (i)Chip boards have 3 different packet RAM size variants: 128K, 512K and - 1M. The RAM size decides the number of buffers and buffer size. The default - size and number of buffers are set as following: + 1M. The RAM size decides the number of buffers and buffer size. The default + size and number of buffers are set as following: - Total Rx RAM Tx RAM Rx Buf Tx Buf Rx buf Tx buf - RAM size size size size size cnt cnt - -------- ------ ------ ------ ------ ------ ------ - 128K 64K 64K 10K 10K 6 6 - 512K 256K 256K 10K 10K 25 25 - 1M 512K 512K 10K 10K 51 51 + ========= ======= ====== ====== ====== ====== ====== + Total Rx RAM Tx RAM Rx Buf Tx Buf Rx buf Tx buf + RAM size size size size size cnt cnt + ========= ======= ====== ====== ====== ====== ====== + 128K 64K 64K 10K 10K 6 6 + 512K 256K 256K 10K 10K 25 25 + 1M 512K 512K 10K 10K 51 51 + ========= ======= ====== ====== ====== ====== ====== These setting should work well in most environments, but can be - changed by typing the following command: - - insmod /ia.o IA_RX_BUF= IA_RX_BUF_SZ= \ - IA_TX_BUF= IA_TX_BUF_SZ= + changed by typing the following command:: + + insmod /ia.o IA_RX_BUF= IA_RX_BUF_SZ= \ + IA_TX_BUF= IA_TX_BUF_SZ= + Where: - RX_CNT = number of receive buffers in the range (1-128) - RX_SIZE = size of receive buffers in the range (48-64K) - TX_CNT = number of transmit buffers in the range (1-128) - TX_SIZE = size of transmit buffers in the range (48-64K) - 1. Transmit and receive buffer size must be a multiple of 4. - 2. Care should be taken so that the memory required for the - transmit and receive buffers is less than or equal to the - total adapter packet memory. + - RX_CNT = number of receive buffers in the range (1-128) + - RX_SIZE = size of receive buffers in the range (48-64K) + - TX_CNT = number of transmit buffers in the range (1-128) + - TX_SIZE = size of transmit buffers in the range (48-64K) + + 1. Transmit and receive buffer size must be a multiple of 4. + 2. Care should be taken so that the memory required for the + transmit and receive buffers is less than or equal to the + total adapter packet memory. 5.2 Turn on ia debug trace - When the ia driver is built with the CONFIG_ATM_IA_DEBUG flag, the driver - can provide more debug trace if needed. There is a bit mask variable, - IADebugFlag, which controls the output of the traces. You can find the bit - map of the IADebugFlag in iphase.h. - The debug trace can be turn on through the insmod command line option, for - example, "insmod iphase.o IADebugFlag=0xffffffff" can turn on all the debug + When the ia driver is built with the CONFIG_ATM_IA_DEBUG flag, the driver + can provide more debug trace if needed. There is a bit mask variable, + IADebugFlag, which controls the output of the traces. You can find the bit + map of the IADebugFlag in iphase.h. + The debug trace can be turn on through the insmod command line option, for + example, "insmod iphase.o IADebugFlag=0xffffffff" can turn on all the debug traces together with loading the driver. 6. Ia Driver Test Using ttcp_atm and PVC - For the PVC setup, the test machines can either be connected back-to-back or - through a switch. If connected through the switch, the switch must be + For the PVC setup, the test machines can either be connected back-to-back or + through a switch. If connected through the switch, the switch must be configured for the PVC(s). a. For UBR test: - At the test machine intended to receive data, type: - ttcp_atm -r -a -s 0.100 - At the other test machine, type: - ttcp_atm -t -a -s 0.100 -n 10000 + + At the test machine intended to receive data, type:: + + ttcp_atm -r -a -s 0.100 + + At the other test machine, type:: + + ttcp_atm -t -a -s 0.100 -n 10000 + Run "ttcp_atm -h" to display more options of the ttcp_atm tool. b. For ABR test: - It is the same as the UBR testing, but with an extra command option: - -Pabr:max_pcr= - where: - xxx = the maximum peak cell rate, from 170 - 353207. - This option must be set on both the machines. + + It is the same as the UBR testing, but with an extra command option:: + + -Pabr:max_pcr= + + where: + + xxx = the maximum peak cell rate, from 170 - 353207. + + This option must be set on both the machines. + c. For CBR test: - It is the same as the UBR testing, but with an extra command option: - -Pcbr:max_pcr= - where: - xxx = the maximum peak cell rate, from 170 - 353207. - This option may only be set on the transmit machine. + It is the same as the UBR testing, but with an extra command option:: -OUTSTANDING ISSUES ------------------- + -Pcbr:max_pcr= + + where: + + xxx = the maximum peak cell rate, from 170 - 353207. + + This option may only be set on the transmit machine. + + +Outstanding Issues +================== Contact Information ------------------- +:: + Customer Support: - United States: Telephone: (214) 654-5555 - Fax: (214) 654-5500 + United States: Telephone: (214) 654-5555 + Fax: (214) 654-5500 E-Mail: intouch@iphase.com Europe: Telephone: 33 (0)1 41 15 44 00 Fax: 33 (0)1 41 15 12 13 diff --git a/drivers/atm/Kconfig b/drivers/atm/Kconfig index 4af7cbdcc349..cfb0d16b60ad 100644 --- a/drivers/atm/Kconfig +++ b/drivers/atm/Kconfig @@ -306,7 +306,7 @@ config ATM_IA for more info about the cards. Say Y (or M to compile as a module named iphase) here if you have one of these cards. - See the file for further + See the file for further details. config ATM_IA_DEBUG From patchwork Mon Apr 27 22:01:48 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Mauro Carvalho Chehab X-Patchwork-Id: 220453 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-10.1 required=3.0 tests=DKIMWL_WL_HIGH, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, INCLUDES_PATCH, MAILING_LIST_MULTI, SIGNED_OFF_BY, SPF_HELO_NONE,SPF_PASS,USER_AGENT_GIT autolearn=unavailable autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 9142FC82A06 for ; Mon, 27 Apr 2020 22:03:24 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 6F6702082E for ; Mon, 27 Apr 2020 22:03:24 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1588025004; bh=L4jsQdJmt6d0yWzSleeuXlGAkK6kzaQF1GdzgV3kZc4=; h=From:To:Cc:Subject:Date:In-Reply-To:References:List-ID:From; b=l3QRuB5yfL0O2ZulBKbMMxJtDF/mhlqNclL6Ah1kR2nx4rLnB+oqPpk+CRmTRu8Rw gR0Vv3UjKHUj1aGNxZh8B7GHbYiGSnaEThDez55knQHvRMQY38duBPXpze+BbJnPhX aoO0W2uN+bC6SVmP0eVf/tR2N5CySjwTAxkjZHL8= Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1726691AbgD0WDX (ORCPT ); Mon, 27 Apr 2020 18:03:23 -0400 Received: from mail.kernel.org ([198.145.29.99]:48022 "EHLO mail.kernel.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726399AbgD0WCB (ORCPT ); Mon, 27 Apr 2020 18:02:01 -0400 Received: from mail.kernel.org (ip5f5ad5c5.dynamic.kabel-deutschland.de [95.90.213.197]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPSA id 1415422264; Mon, 27 Apr 2020 22:01:57 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1588024917; bh=L4jsQdJmt6d0yWzSleeuXlGAkK6kzaQF1GdzgV3kZc4=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=QYHKJJssIrgo6GJ3mv8JXe9TeUyyOGOBVLI3T9YaQJgr++IY+Nkthanpoy1XrXd+3 CcdolwrZDN3G6upfGMBkmOi7ud0Ws/Tr9D+OMyFqW2fxhsBfjjgrJDggqds35hAv4U FkpS+1Zl/z4+fcYM48Xc760R+RDVVtK2tNSMNrjM= Received: from mchehab by mail.kernel.org with local (Exim 4.92.3) (envelope-from ) id 1jTBp5-000IqH-Bv; Tue, 28 Apr 2020 00:01:55 +0200 From: Mauro Carvalho Chehab To: Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Jonathan Corbet , "David S. Miller" , Jakub Kicinski , netdev@vger.kernel.org Subject: [PATCH 33/38] docs: networking: convert ipsec.txt to ReST Date: Tue, 28 Apr 2020 00:01:48 +0200 Message-Id: <448fc25ca83dcc01bedfe36b27966b670a87a7b0.1588024424.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.25.4 In-Reply-To: References: MIME-Version: 1.0 Sender: netdev-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: netdev@vger.kernel.org Not much to be done here: - add SPDX header; - add a document title; - adjust identation, whitespaces and blank lines; - add to networking/index.rst. Signed-off-by: Mauro Carvalho Chehab --- Documentation/networking/index.rst | 1 + Documentation/networking/{ipsec.txt => ipsec.rst} | 14 +++++++++++--- 2 files changed, 12 insertions(+), 3 deletions(-) rename Documentation/networking/{ipsec.txt => ipsec.rst} (90%) diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst index 505eaa41ca2b..3efb4608649a 100644 --- a/Documentation/networking/index.rst +++ b/Documentation/networking/index.rst @@ -68,6 +68,7 @@ Contents: ipddp ip_dynaddr iphase + ipsec .. only:: subproject and html diff --git a/Documentation/networking/ipsec.txt b/Documentation/networking/ipsec.rst similarity index 90% rename from Documentation/networking/ipsec.txt rename to Documentation/networking/ipsec.rst index ba794b7e51be..afe9d7b48be3 100644 --- a/Documentation/networking/ipsec.txt +++ b/Documentation/networking/ipsec.rst @@ -1,12 +1,20 @@ +.. SPDX-License-Identifier: GPL-2.0 + +===== +IPsec +===== + Here documents known IPsec corner cases which need to be keep in mind when deploy various IPsec configuration in real world production environment. -1. IPcomp: Small IP packet won't get compressed at sender, and failed on +1. IPcomp: + Small IP packet won't get compressed at sender, and failed on policy check on receiver. -Quote from RFC3173: -2.2. Non-Expansion Policy +Quote from RFC3173:: + + 2.2. Non-Expansion Policy If the total size of a compressed payload and the IPComp header, as defined in section 3, is not smaller than the size of the original From patchwork Mon Apr 27 22:01:49 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Mauro Carvalho Chehab X-Patchwork-Id: 220457 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-10.1 required=3.0 tests=DKIMWL_WL_HIGH, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, INCLUDES_PATCH, MAILING_LIST_MULTI, SIGNED_OFF_BY, SPF_HELO_NONE,SPF_PASS,USER_AGENT_GIT autolearn=unavailable autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id B7E53C82A02 for ; Mon, 27 Apr 2020 22:02:39 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 791F321775 for ; Mon, 27 Apr 2020 22:02:39 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1588024959; bh=B0tMPR6+mh208jit95b6cw+WD4mUBQOHposd+FXdKR0=; h=From:To:Cc:Subject:Date:In-Reply-To:References:List-ID:From; b=WT1RMN5d362PBw3MZ5MdHf4sKnQ2DwUB+4Zmw7rWkawhCrrWFJ220tivBSCyACMg5 mTWKNhfJm5bMsXOrlR/i6ApvwdEqmKFmwhqFSiAMmiNs7l7qz85wK6VcjVixyYaMJM VJpBVILQ1EAH9d2tc/dCoLUAhR/JUoE7iC0F3Cmg= Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1726550AbgD0WCg (ORCPT ); Mon, 27 Apr 2020 18:02:36 -0400 Received: from mail.kernel.org ([198.145.29.99]:48124 "EHLO mail.kernel.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726405AbgD0WCD (ORCPT ); Mon, 27 Apr 2020 18:02:03 -0400 Received: from mail.kernel.org (ip5f5ad5c5.dynamic.kabel-deutschland.de [95.90.213.197]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPSA id 2065D22277; Mon, 27 Apr 2020 22:01:57 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1588024917; bh=B0tMPR6+mh208jit95b6cw+WD4mUBQOHposd+FXdKR0=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=OIQ7XYjzVKwheJAka9NvRphrqclcqYWdQDB987T+sJA28+2L05PHu5rvxrS/UxvY/ oHglwj1Ff8dyj7Ete/4md8PIlg6CFf76TThAiFo899Rtbw45wV7m/cakf4DuP1zdkV VOH5KSnAP6xq4voa/9b+BwrNnbqkaMTvyaml2ERw= Received: from mchehab by mail.kernel.org with local (Exim 4.92.3) (envelope-from ) id 1jTBp5-000IqN-Cr; Tue, 28 Apr 2020 00:01:55 +0200 From: Mauro Carvalho Chehab To: Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Jonathan Corbet , "David S. Miller" , Jakub Kicinski , Alexey Kuznetsov , Hideaki YOSHIFUJI , netdev@vger.kernel.org Subject: [PATCH 34/38] docs: networking: convert ip-sysctl.txt to ReST Date: Tue, 28 Apr 2020 00:01:49 +0200 Message-Id: X-Mailer: git-send-email 2.25.4 In-Reply-To: References: MIME-Version: 1.0 Sender: netdev-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: netdev@vger.kernel.org - add SPDX header; - adjust titles and chapters, adding proper markups; - mark code blocks and literals as such; - mark lists as such; - mark tables as such; - use footnote markup; - adjust identation, whitespaces and blank lines; - add to networking/index.rst. Signed-off-by: Mauro Carvalho Chehab --- .../admin-guide/kernel-parameters.txt | 2 +- Documentation/admin-guide/sysctl/net.rst | 2 +- Documentation/networking/index.rst | 1 + .../{ip-sysctl.txt => ip-sysctl.rst} | 829 ++++++++++++------ Documentation/networking/snmp_counter.rst | 2 +- net/Kconfig | 2 +- net/ipv4/Kconfig | 2 +- net/ipv4/icmp.c | 2 +- 8 files changed, 559 insertions(+), 283 deletions(-) rename Documentation/networking/{ip-sysctl.txt => ip-sysctl.rst} (83%) diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt index cd68635370c6..ef9779398cee 100644 --- a/Documentation/admin-guide/kernel-parameters.txt +++ b/Documentation/admin-guide/kernel-parameters.txt @@ -4950,7 +4950,7 @@ Set the number of tcp_metrics_hash slots. Default value is 8192 or 16384 depending on total ram pages. This is used to specify the TCP metrics - cache size. See Documentation/networking/ip-sysctl.txt + cache size. See Documentation/networking/ip-sysctl.rst "tcp_no_metrics_save" section for more details. tdfx= [HW,DRM] diff --git a/Documentation/admin-guide/sysctl/net.rst b/Documentation/admin-guide/sysctl/net.rst index e043c9213388..84e3348a9543 100644 --- a/Documentation/admin-guide/sysctl/net.rst +++ b/Documentation/admin-guide/sysctl/net.rst @@ -353,7 +353,7 @@ socket's buffer. It will not take effect unless PF_UNIX flag is specified. 3. /proc/sys/net/ipv4 - IPV4 settings ------------------------------------- -Please see: Documentation/networking/ip-sysctl.txt and ipvs-sysctl.txt for +Please see: Documentation/networking/ip-sysctl.rst and ipvs-sysctl.txt for descriptions of these entries. diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst index 3efb4608649a..7d133d8dbe2a 100644 --- a/Documentation/networking/index.rst +++ b/Documentation/networking/index.rst @@ -69,6 +69,7 @@ Contents: ip_dynaddr iphase ipsec + ip-sysctl .. only:: subproject and html diff --git a/Documentation/networking/ip-sysctl.txt b/Documentation/networking/ip-sysctl.rst similarity index 83% rename from Documentation/networking/ip-sysctl.txt rename to Documentation/networking/ip-sysctl.rst index 9375324aa8e1..65374ffaafb8 100644 --- a/Documentation/networking/ip-sysctl.txt +++ b/Documentation/networking/ip-sysctl.rst @@ -1,8 +1,15 @@ -/proc/sys/net/ipv4/* Variables: +.. SPDX-License-Identifier: GPL-2.0 + +========= +IP Sysctl +========= + +/proc/sys/net/ipv4/* Variables +============================== ip_forward - BOOLEAN - 0 - disabled (default) - not 0 - enabled + - 0 - disabled (default) + - not 0 - enabled Forward Packets between interfaces. @@ -38,6 +45,7 @@ ip_no_pmtu_disc - INTEGER could break other protocols. Possible values: 0-3 + Default: FALSE min_pmtu - INTEGER @@ -51,16 +59,20 @@ ip_forward_use_pmtu - BOOLEAN which tries to discover path mtus by itself and depends on the kernel honoring this information. This is normally not the case. + Default: 0 (disabled) + Possible values: - 0 - disabled - 1 - enabled + + - 0 - disabled + - 1 - enabled fwmark_reflect - BOOLEAN Controls the fwmark of kernel-generated IPv4 reply packets that are not associated with a socket for example, TCP RSTs or ICMP echo replies). If unset, these packets have a fwmark of zero. If set, they have the fwmark of the packet they are replying to. + Default: 0 fib_multipath_use_neigh - BOOLEAN @@ -68,63 +80,80 @@ fib_multipath_use_neigh - BOOLEAN multipath routes. If disabled, neighbor information is not used and packets could be directed to a failed nexthop. Only valid for kernels built with CONFIG_IP_ROUTE_MULTIPATH enabled. + Default: 0 (disabled) + Possible values: - 0 - disabled - 1 - enabled + + - 0 - disabled + - 1 - enabled fib_multipath_hash_policy - INTEGER Controls which hash policy to use for multipath routes. Only valid for kernels built with CONFIG_IP_ROUTE_MULTIPATH enabled. + Default: 0 (Layer 3) + Possible values: - 0 - Layer 3 - 1 - Layer 4 - 2 - Layer 3 or inner Layer 3 if present + + - 0 - Layer 3 + - 1 - Layer 4 + - 2 - Layer 3 or inner Layer 3 if present fib_sync_mem - UNSIGNED INTEGER Amount of dirty memory from fib entries that can be backlogged before synchronize_rcu is forced. - Default: 512kB Minimum: 64kB Maximum: 64MB + + Default: 512kB Minimum: 64kB Maximum: 64MB ip_forward_update_priority - INTEGER Whether to update SKB priority from "TOS" field in IPv4 header after it is forwarded. The new SKB priority is mapped from TOS field value according to an rt_tos2priority table (see e.g. man tc-prio). + Default: 1 (Update priority.) + Possible values: - 0 - Do not update priority. - 1 - Update priority. + + - 0 - Do not update priority. + - 1 - Update priority. route/max_size - INTEGER Maximum number of routes allowed in the kernel. Increase this when using large numbers of interfaces and/or routes. + From linux kernel 3.6 onwards, this is deprecated for ipv4 as route cache is no longer used. neigh/default/gc_thresh1 - INTEGER Minimum number of entries to keep. Garbage collector will not purge entries if there are fewer than this number. + Default: 128 neigh/default/gc_thresh2 - INTEGER Threshold when garbage collector becomes more aggressive about purging entries. Entries older than 5 seconds will be cleared when over this number. + Default: 512 neigh/default/gc_thresh3 - INTEGER Maximum number of non-PERMANENT neighbor entries allowed. Increase this when using large numbers of interfaces and when communicating with large numbers of directly-connected peers. + Default: 1024 neigh/default/unres_qlen_bytes - INTEGER The maximum number of bytes which may be used by packets queued for each unresolved address by other network layers. (added in linux 3.3) + Setting negative value is meaningless and will return error. + Default: SK_WMEM_MAX, (same as net.core.wmem_default). + Exact value depends on architecture and kernel options, but should be enough to allow queuing 256 packets of medium size. @@ -132,11 +161,14 @@ neigh/default/unres_qlen_bytes - INTEGER neigh/default/unres_qlen - INTEGER The maximum number of packets which may be queued for each unresolved address by other network layers. + (deprecated in linux 3.3) : use unres_qlen_bytes instead. + Prior to linux 3.3, the default value is 3 which may cause unexpected packet loss. The current default value is calculated according to default value of unres_qlen_bytes and true size of packet. + Default: 101 mtu_expires - INTEGER @@ -183,7 +215,8 @@ ipfrag_max_dist - INTEGER from different IP datagrams, which could result in data corruption. Default: 64 -INET peer storage: +INET peer storage +================= inet_peer_threshold - INTEGER The approximate size of the storage. Starting from this threshold @@ -203,7 +236,8 @@ inet_peer_maxttl - INTEGER when the number of entries in the pool is very small). Measured in seconds. -TCP variables: +TCP variables +============= somaxconn - INTEGER Limit of socket listen() backlog, known in userspace as SOMAXCONN. @@ -222,18 +256,22 @@ tcp_adv_win_scale - INTEGER Count buffering overhead as bytes/2^tcp_adv_win_scale (if tcp_adv_win_scale > 0) or bytes-bytes/2^(-tcp_adv_win_scale), if it is <= 0. + Possible values are [-31, 31], inclusive. + Default: 1 tcp_allowed_congestion_control - STRING Show/set the congestion control choices available to non-privileged processes. The list is a subset of those listed in tcp_available_congestion_control. + Default is "reno" and the default setting (tcp_congestion_control). tcp_app_win - INTEGER Reserve max(window/2^tcp_app_win, mss) of window for application buffer. Value 0 is special, it means that nothing is reserved. + Default: 31 tcp_autocorking - BOOLEAN @@ -244,6 +282,7 @@ tcp_autocorking - BOOLEAN packet for the flow is waiting in Qdisc queues or device transmit queue. Applications can still use TCP_CORK for optimal behavior when they know how/when to uncork their sockets. + Default : 1 tcp_available_congestion_control - STRING @@ -265,6 +304,7 @@ tcp_mtu_probe_floor - INTEGER tcp_min_snd_mss - INTEGER TCP SYN and SYNACK messages usually advertise an ADVMSS option, as described in RFC 1122 and RFC 6691. + If this ADVMSS option is smaller than tcp_min_snd_mss, it is silently capped to tcp_min_snd_mss. @@ -277,6 +317,7 @@ tcp_congestion_control - STRING Default is set as part of kernel configuration. For passive connections, the listener congestion control choice is inherited. + [see setsockopt(listenfd, SOL_TCP, TCP_CONGESTION, "name" ...) ] tcp_dsack - BOOLEAN @@ -286,9 +327,12 @@ tcp_early_retrans - INTEGER Tail loss probe (TLP) converts RTOs occurring due to tail losses into fast recovery (draft-ietf-tcpm-rack). Note that TLP requires RACK to function properly (see tcp_recovery below) + Possible values: - 0 disables TLP - 3 or 4 enables TLP + + - 0 disables TLP + - 3 or 4 enables TLP + Default: 3 tcp_ecn - INTEGER @@ -297,12 +341,17 @@ tcp_ecn - INTEGER support for it. This feature is useful in avoiding losses due to congestion by allowing supporting routers to signal congestion before having to drop packets. + Possible values are: - 0 Disable ECN. Neither initiate nor accept ECN. - 1 Enable ECN when requested by incoming connections and - also request ECN on outgoing connection attempts. - 2 Enable ECN when requested by incoming connections - but do not request ECN on outgoing connections. + + = ===================================================== + 0 Disable ECN. Neither initiate nor accept ECN. + 1 Enable ECN when requested by incoming connections and + also request ECN on outgoing connection attempts. + 2 Enable ECN when requested by incoming connections + but do not request ECN on outgoing connections. + = ===================================================== + Default: 2 tcp_ecn_fallback - BOOLEAN @@ -312,6 +361,7 @@ tcp_ecn_fallback - BOOLEAN additional detection mechanisms could be implemented under this knob. The value is not used, if tcp_ecn or per route (or congestion control) ECN settings are disabled. + Default: 1 (fallback enabled) tcp_fack - BOOLEAN @@ -324,7 +374,9 @@ tcp_fin_timeout - INTEGER valid "receive only" state for an un-orphaned connection, an orphaned connection in FIN_WAIT_2 state could otherwise wait forever for the remote to close its end of the connection. + Cf. tcp_max_orphans + Default: 60 seconds tcp_frto - INTEGER @@ -390,7 +442,8 @@ tcp_l3mdev_accept - BOOLEAN derived from the listen socket to be bound to the L3 domain in which the packets originated. Only valid when the kernel was compiled with CONFIG_NET_L3_MASTER_DEV. - Default: 0 (disabled) + + Default: 0 (disabled) tcp_low_latency - BOOLEAN This is a legacy option, it has no effect anymore. @@ -410,10 +463,14 @@ tcp_max_orphans - INTEGER tcp_max_syn_backlog - INTEGER Maximal number of remembered connection requests (SYN_RECV), which have not received an acknowledgment from connecting client. + This is a per-listener limit. + The minimal value is 128 for low memory machines, and it will increase in proportion to the memory of machine. + If server suffers from overload, try increasing this number. + Remember to also check /proc/sys/net/core/somaxconn A SYN_RECV request socket consumes about 304 bytes of memory. @@ -445,7 +502,9 @@ tcp_min_rtt_wlen - INTEGER minimum RTT when it is moved to a longer path (e.g., due to traffic engineering). A longer window makes the filter more resistant to RTT inflations such as transient congestion. The unit is seconds. + Possible values: 0 - 86400 (1 day) + Default: 300 tcp_moderate_rcvbuf - BOOLEAN @@ -457,9 +516,10 @@ tcp_moderate_rcvbuf - BOOLEAN tcp_mtu_probing - INTEGER Controls TCP Packetization-Layer Path MTU Discovery. Takes three values: - 0 - Disabled - 1 - Disabled by default, enabled when an ICMP black hole detected - 2 - Always enabled, use initial MSS of tcp_base_mss. + + - 0 - Disabled + - 1 - Disabled by default, enabled when an ICMP black hole detected + - 2 - Always enabled, use initial MSS of tcp_base_mss. tcp_probe_interval - UNSIGNED INTEGER Controls how often to start TCP Packetization-Layer Path MTU @@ -481,6 +541,7 @@ tcp_no_metrics_save - BOOLEAN tcp_no_ssthresh_metrics_save - BOOLEAN Controls whether TCP saves ssthresh metrics in the route cache. + Default is 1, which disables ssthresh metrics. tcp_orphan_retries - INTEGER @@ -489,6 +550,7 @@ tcp_orphan_retries - INTEGER See tcp_retries2 for more details. The default value is 8. + If your machine is a loaded WEB server, you should think about lowering this value, such sockets may consume significant resources. Cf. tcp_max_orphans. @@ -497,11 +559,15 @@ tcp_recovery - INTEGER This value is a bitmap to enable various experimental loss recovery features. - RACK: 0x1 enables the RACK loss detection for fast detection of lost - retransmissions and tail drops. It also subsumes and disables - RFC6675 recovery for SACK connections. - RACK: 0x2 makes RACK's reordering window static (min_rtt/4). - RACK: 0x4 disables RACK's DUPACK threshold heuristic + ========= ============================================================= + RACK: 0x1 enables the RACK loss detection for fast detection of lost + retransmissions and tail drops. It also subsumes and disables + RFC6675 recovery for SACK connections. + + RACK: 0x2 makes RACK's reordering window static (min_rtt/4). + + RACK: 0x4 disables RACK's DUPACK threshold heuristic + ========= ============================================================= Default: 0x1 @@ -509,12 +575,14 @@ tcp_reordering - INTEGER Initial reordering level of packets in a TCP stream. TCP stack can then dynamically adjust flow reordering level between this initial value and tcp_max_reordering + Default: 3 tcp_max_reordering - INTEGER Maximal reordering level of packets in a TCP stream. 300 is a fairly conservative value, but you might increase it if paths are using per packet load balancing (like bonding rr mode) + Default: 300 tcp_retrans_collapse - BOOLEAN @@ -550,12 +618,14 @@ tcp_rfc1337 - BOOLEAN If set, the TCP stack behaves conforming to RFC1337. If unset, we are not conforming to RFC, but prevent TCP TIME_WAIT assassination. + Default: 0 tcp_rmem - vector of 3 INTEGERs: min, default, max min: Minimal size of receive buffer used by TCP sockets. It is guaranteed to each TCP socket, even under moderate memory pressure. + Default: 4K default: initial size of receive buffer used by TCP sockets. @@ -592,12 +662,14 @@ tcp_slow_start_after_idle - BOOLEAN window after an idle period. An idle period is defined at the current RTO. If unset, the congestion window will not be timed out after an idle period. + Default: 1 tcp_stdurg - BOOLEAN Use the Host requirements interpretation of the TCP urgent pointer field. Most hosts use the older BSD interpretation, so if you turn this on Linux might not communicate correctly with them. + Default: FALSE tcp_synack_retries - INTEGER @@ -646,15 +718,18 @@ tcp_fastopen - INTEGER the option value being the length of the syn-data backlog. The values (bitmap) are - 0x1: (client) enables sending data in the opening SYN on the client. - 0x2: (server) enables the server support, i.e., allowing data in + + ===== ======== ====================================================== + 0x1 (client) enables sending data in the opening SYN on the client. + 0x2 (server) enables the server support, i.e., allowing data in a SYN packet to be accepted and passed to the application before 3-way handshake finishes. - 0x4: (client) send data in the opening SYN regardless of cookie + 0x4 (client) send data in the opening SYN regardless of cookie availability and without a cookie option. - 0x200: (server) accept data-in-SYN w/o any cookie option present. - 0x400: (server) enable all listeners to support Fast Open by + 0x200 (server) accept data-in-SYN w/o any cookie option present. + 0x400 (server) enable all listeners to support Fast Open by default without explicit TCP_FASTOPEN socket option. + ===== ======== ====================================================== Default: 0x1 @@ -668,6 +743,7 @@ tcp_fastopen_blackhole_timeout_sec - INTEGER get detected right after Fastopen is re-enabled and will reset to initial value when the blackhole issue goes away. 0 to disable the blackhole detection. + By default, it is set to 1hr. tcp_fastopen_key - list of comma separated 32-digit hexadecimal INTEGERs @@ -698,20 +774,24 @@ tcp_syn_retries - INTEGER for an active TCP connection attempt will happen after 127seconds. tcp_timestamps - INTEGER -Enable timestamps as defined in RFC1323. - 0: Disabled. - 1: Enable timestamps as defined in RFC1323 and use random offset for - each connection rather than only using the current time. - 2: Like 1, but without random offsets. + Enable timestamps as defined in RFC1323. + + - 0: Disabled. + - 1: Enable timestamps as defined in RFC1323 and use random offset for + each connection rather than only using the current time. + - 2: Like 1, but without random offsets. + Default: 1 tcp_min_tso_segs - INTEGER Minimal number of segments per TSO frame. + Since linux-3.12, TCP does an automatic sizing of TSO frames, depending on flow rate, instead of filling 64Kbytes packets. For specific usages, it's possible to force TCP to build big TSO frames. Note that TCP stack might split too big TSO packets if available window is too small. + Default: 2 tcp_pacing_ss_ratio - INTEGER @@ -720,6 +800,7 @@ tcp_pacing_ss_ratio - INTEGER If TCP is in slow start, tcp_pacing_ss_ratio is applied to let TCP probe for bigger speeds, assuming cwnd can be doubled every other RTT. + Default: 200 tcp_pacing_ca_ratio - INTEGER @@ -727,6 +808,7 @@ tcp_pacing_ca_ratio - INTEGER to current rate. (current_rate = cwnd * mss / srtt) If TCP is in congestion avoidance phase, tcp_pacing_ca_ratio is applied to conservatively probe for bigger throughput. + Default: 120 tcp_tso_win_divisor - INTEGER @@ -734,16 +816,20 @@ tcp_tso_win_divisor - INTEGER can be consumed by a single TSO frame. The setting of this parameter is a choice between burstiness and building larger TSO frames. + Default: 3 tcp_tw_reuse - INTEGER Enable reuse of TIME-WAIT sockets for new connections when it is safe from protocol viewpoint. - 0 - disable - 1 - global enable - 2 - enable for loopback traffic only + + - 0 - disable + - 1 - global enable + - 2 - enable for loopback traffic only + It should not be changed without advice/request of technical experts. + Default: 2 tcp_window_scaling - BOOLEAN @@ -752,11 +838,14 @@ tcp_window_scaling - BOOLEAN tcp_wmem - vector of 3 INTEGERs: min, default, max min: Amount of memory reserved for send buffers for TCP sockets. Each TCP socket has rights to use it due to fact of its birth. + Default: 4K default: initial size of send buffer used by TCP sockets. This value overrides net.core.wmem_default used by other protocols. + It is usually lower than net.core.wmem_default. + Default: 16K max: Maximal amount of memory allowed for automatically tuned @@ -764,6 +853,7 @@ tcp_wmem - vector of 3 INTEGERs: min, default, max net.core.wmem_max. Calling setsockopt() with SO_SNDBUF disables automatic tuning of that socket's send buffer size, in which case this value is ignored. + Default: between 64K and 4MB, depending on RAM size. tcp_notsent_lowat - UNSIGNED INTEGER @@ -784,6 +874,7 @@ tcp_workaround_signed_windows - BOOLEAN remote TCP is broken and treats the window as a signed quantity. If unset, assume the remote TCP is not broken even if we do not receive a window scaling option from them. + Default: 0 tcp_thin_linear_timeouts - BOOLEAN @@ -796,6 +887,7 @@ tcp_thin_linear_timeouts - BOOLEAN non-aggressive thin streams, often found to be time-dependent. For more information on thin streams, see Documentation/networking/tcp-thin.txt + Default: 0 tcp_limit_output_bytes - INTEGER @@ -807,6 +899,7 @@ tcp_limit_output_bytes - INTEGER flows, for typical pfifo_fast qdiscs. tcp_limit_output_bytes limits the number of bytes on qdisc or device to reduce artificial RTT/cwnd and reduce bufferbloat. + Default: 1048576 (16 * 65536) tcp_challenge_ack_limit - INTEGER @@ -822,7 +915,8 @@ tcp_rx_skb_cache - BOOLEAN Default: 0 (disabled) -UDP variables: +UDP variables +============= udp_l3mdev_accept - BOOLEAN Enabling this option allows a "global" bound socket to work @@ -830,7 +924,8 @@ udp_l3mdev_accept - BOOLEAN being received regardless of the L3 domain in which they originated. Only valid when the kernel was compiled with CONFIG_NET_L3_MASTER_DEV. - Default: 0 (disabled) + + Default: 0 (disabled) udp_mem - vector of 3 INTEGERs: min, pressure, max Number of pages allowed for queueing by all UDP sockets. @@ -849,15 +944,18 @@ udp_rmem_min - INTEGER Minimal size of receive buffer used by UDP sockets in moderation. Each UDP socket is able to use the size for receiving data, even if total pages of UDP sockets exceed udp_mem pressure. The unit is byte. + Default: 4K udp_wmem_min - INTEGER Minimal size of send buffer used by UDP sockets in moderation. Each UDP socket is able to use the size for sending data, even if total pages of UDP sockets exceed udp_mem pressure. The unit is byte. + Default: 4K -RAW variables: +RAW variables +============= raw_l3mdev_accept - BOOLEAN Enabling this option allows a "global" bound socket to work @@ -865,9 +963,11 @@ raw_l3mdev_accept - BOOLEAN being received regardless of the L3 domain in which they originated. Only valid when the kernel was compiled with CONFIG_NET_L3_MASTER_DEV. + Default: 1 (enabled) -CIPSOv4 Variables: +CIPSOv4 Variables +================= cipso_cache_enable - BOOLEAN If set, enable additions to and lookups from the CIPSO label mapping @@ -875,6 +975,7 @@ cipso_cache_enable - BOOLEAN miss. However, regardless of the setting the cache is still invalidated when required when means you can safely toggle this on and off and the cache will always be "safe". + Default: 1 cipso_cache_bucket_size - INTEGER @@ -884,6 +985,7 @@ cipso_cache_bucket_size - INTEGER more CIPSO label mappings that can be cached. When the number of entries in a given hash bucket reaches this limit adding new entries causes the oldest entry in the bucket to be removed to make room. + Default: 10 cipso_rbm_optfmt - BOOLEAN @@ -891,6 +993,7 @@ cipso_rbm_optfmt - BOOLEAN the CIPSO draft specification (see Documentation/netlabel for details). This means that when set the CIPSO tag will be padded with empty categories in order to make the packet data 32-bit aligned. + Default: 0 cipso_rbm_structvalid - BOOLEAN @@ -900,9 +1003,11 @@ cipso_rbm_structvalid - BOOLEAN where in the CIPSO processing code but setting this to 0 (False) should result in less work (i.e. it should be faster) but could cause problems with other implementations that require strict checking. + Default: 0 -IP Variables: +IP Variables +============ ip_local_port_range - 2 INTEGERS Defines the local port range that is used by TCP and UDP to @@ -931,12 +1036,12 @@ ip_local_reserved_ports - list of comma separated ranges assignments. You can reserve ports which are not in the current - ip_local_port_range, e.g.: + ip_local_port_range, e.g.:: - $ cat /proc/sys/net/ipv4/ip_local_port_range - 32000 60999 - $ cat /proc/sys/net/ipv4/ip_local_reserved_ports - 8080,9148 + $ cat /proc/sys/net/ipv4/ip_local_port_range + 32000 60999 + $ cat /proc/sys/net/ipv4/ip_local_reserved_ports + 8080,9148 although this is redundant. However such a setting is useful if later the port range is changed to a value that will @@ -956,6 +1061,7 @@ ip_unprivileged_port_start - INTEGER ip_nonlocal_bind - BOOLEAN If set, allows processes to bind() to non-local IP addresses, which can be quite useful - but may break some applications. + Default: 0 ip_autobind_reuse - BOOLEAN @@ -972,6 +1078,7 @@ ip_dynaddr - BOOLEAN If set to a non-zero value larger than 1, a kernel log message will be printed when dynamic address rewriting occurs. + Default: 0 ip_early_demux - BOOLEAN @@ -981,6 +1088,7 @@ ip_early_demux - BOOLEAN It may add an additional cost for pure routing workloads that reduces overall throughput, in such case you should disable it. + Default: 1 ping_group_range - 2 INTEGERS @@ -992,21 +1100,25 @@ ping_group_range - 2 INTEGERS tcp_early_demux - BOOLEAN Enable early demux for established TCP sockets. + Default: 1 udp_early_demux - BOOLEAN Enable early demux for connected UDP sockets. Disable this if your system could experience more unconnected load. + Default: 1 icmp_echo_ignore_all - BOOLEAN If set non-zero, then the kernel will ignore all ICMP ECHO requests sent to it. + Default: 0 icmp_echo_ignore_broadcasts - BOOLEAN If set non-zero, then the kernel will ignore all ICMP ECHO and TIMESTAMP requests sent to it via broadcast/multicast. + Default: 1 icmp_ratelimit - INTEGER @@ -1016,46 +1128,55 @@ icmp_ratelimit - INTEGER otherwise the minimal space between responses in milliseconds. Note that another sysctl, icmp_msgs_per_sec limits the number of ICMP packets sent on all targets. + Default: 1000 icmp_msgs_per_sec - INTEGER Limit maximal number of ICMP packets sent per second from this host. Only messages whose type matches icmp_ratemask (see below) are controlled by this limit. + Default: 1000 icmp_msgs_burst - INTEGER icmp_msgs_per_sec controls number of ICMP packets sent per second, while icmp_msgs_burst controls the burst size of these packets. + Default: 50 icmp_ratemask - INTEGER Mask made of ICMP types for which rates are being limited. + Significant bits: IHGFEDCBA9876543210 + Default mask: 0000001100000011000 (6168) Bit definitions (see include/linux/icmp.h): + + = ========================= 0 Echo Reply - 3 Destination Unreachable * - 4 Source Quench * + 3 Destination Unreachable [1]_ + 4 Source Quench [1]_ 5 Redirect 8 Echo Request - B Time Exceeded * - C Parameter Problem * + B Time Exceeded [1]_ + C Parameter Problem [1]_ D Timestamp Request E Timestamp Reply F Info Request G Info Reply H Address Mask Request I Address Mask Reply + = ========================= - * These are rate limited by default (see default mask above) + .. [1] These are rate limited by default (see default mask above) icmp_ignore_bogus_error_responses - BOOLEAN Some routers violate RFC1122 by sending bogus responses to broadcast frames. Such violations are normally logged via a kernel warning. If this is set to TRUE, the kernel will not give such warnings, which will avoid log file clutter. + Default: 1 icmp_errors_use_inbound_ifaddr - BOOLEAN @@ -1100,32 +1221,39 @@ igmp_max_memberships - INTEGER igmp_max_msf - INTEGER Maximum number of addresses allowed in the source filter list for a multicast group. + Default: 10 igmp_qrv - INTEGER Controls the IGMP query robustness variable (see RFC2236 8.1). + Default: 2 (as specified by RFC2236 8.1) + Minimum: 1 (as specified by RFC6636 4.5) force_igmp_version - INTEGER - 0 - (default) No enforcement of a IGMP version, IGMPv1/v2 fallback - allowed. Will back to IGMPv3 mode again if all IGMPv1/v2 Querier - Present timer expires. - 1 - Enforce to use IGMP version 1. Will also reply IGMPv1 report if - receive IGMPv2/v3 query. - 2 - Enforce to use IGMP version 2. Will fallback to IGMPv1 if receive - IGMPv1 query message. Will reply report if receive IGMPv3 query. - 3 - Enforce to use IGMP version 3. The same react with default 0. + - 0 - (default) No enforcement of a IGMP version, IGMPv1/v2 fallback + allowed. Will back to IGMPv3 mode again if all IGMPv1/v2 Querier + Present timer expires. + - 1 - Enforce to use IGMP version 1. Will also reply IGMPv1 report if + receive IGMPv2/v3 query. + - 2 - Enforce to use IGMP version 2. Will fallback to IGMPv1 if receive + IGMPv1 query message. Will reply report if receive IGMPv3 query. + - 3 - Enforce to use IGMP version 3. The same react with default 0. - Note: this is not the same with force_mld_version because IGMPv3 RFC3376 - Security Considerations does not have clear description that we could - ignore other version messages completely as MLDv2 RFC3810. So make - this value as default 0 is recommended. + .. note:: -conf/interface/* changes special settings per interface (where -"interface" is the name of your network interface) + this is not the same with force_mld_version because IGMPv3 RFC3376 + Security Considerations does not have clear description that we could + ignore other version messages completely as MLDv2 RFC3810. So make + this value as default 0 is recommended. -conf/all/* is special, changes the settings for all interfaces +``conf/interface/*`` + changes special settings per interface (where + interface" is the name of your network interface) + +``conf/all/*`` + is special, changes the settings for all interfaces log_martians - BOOLEAN Log packets with impossible addresses to kernel log. @@ -1136,14 +1264,21 @@ log_martians - BOOLEAN accept_redirects - BOOLEAN Accept ICMP redirect messages. accept_redirects for the interface will be enabled if: + - both conf/{all,interface}/accept_redirects are TRUE in the case forwarding for the interface is enabled + or + - at least one of conf/{all,interface}/accept_redirects is TRUE in the case forwarding for the interface is disabled + accept_redirects for the interface will be disabled otherwise - default TRUE (host) - FALSE (router) + + default: + + - TRUE (host) + - FALSE (router) forwarding - BOOLEAN Enable IP forwarding on this interface. This controls whether packets @@ -1168,12 +1303,14 @@ medium_id - INTEGER proxy_arp - BOOLEAN Do proxy arp. + proxy_arp for the interface will be enabled if at least one of conf/{all,interface}/proxy_arp is set to TRUE, it will be disabled otherwise proxy_arp_pvlan - BOOLEAN Private VLAN proxy arp. + Basically allow proxy arp replies back to the same interface (from which the ARP request/solicitation was received). @@ -1186,6 +1323,7 @@ proxy_arp_pvlan - BOOLEAN proxy_arp. This technology is known by different names: + In RFC 3069 it is called VLAN Aggregation. Cisco and Allied Telesyn call it Private VLAN. Hewlett-Packard call it Source-Port filtering or port-isolation. @@ -1194,26 +1332,33 @@ proxy_arp_pvlan - BOOLEAN shared_media - BOOLEAN Send(router) or accept(host) RFC1620 shared media redirects. Overrides secure_redirects. + shared_media for the interface will be enabled if at least one of conf/{all,interface}/shared_media is set to TRUE, it will be disabled otherwise + default TRUE secure_redirects - BOOLEAN Accept ICMP redirect messages only to gateways listed in the interface's current gateway list. Even if disabled, RFC1122 redirect rules still apply. + Overridden by shared_media. + secure_redirects for the interface will be enabled if at least one of conf/{all,interface}/secure_redirects is set to TRUE, it will be disabled otherwise + default TRUE send_redirects - BOOLEAN Send redirects, if router. + send_redirects for the interface will be enabled if at least one of conf/{all,interface}/send_redirects is set to TRUE, it will be disabled otherwise + Default: TRUE bootp_relay - BOOLEAN @@ -1222,15 +1367,20 @@ bootp_relay - BOOLEAN BOOTP relay daemon will catch and forward such packets. conf/all/bootp_relay must also be set to TRUE to enable BOOTP relay for the interface + default FALSE + Not Implemented Yet. accept_source_route - BOOLEAN Accept packets with SRR option. conf/all/accept_source_route must also be set to TRUE to accept packets with SRR option on the interface - default TRUE (router) - FALSE (host) + + default + + - TRUE (router) + - FALSE (host) accept_local - BOOLEAN Accept packets with local source addresses. In combination with @@ -1241,18 +1391,19 @@ accept_local - BOOLEAN route_localnet - BOOLEAN Do not consider loopback addresses as martian source or destination while routing. This enables the use of 127/8 for local routing purposes. + default FALSE rp_filter - INTEGER - 0 - No source validation. - 1 - Strict mode as defined in RFC3704 Strict Reverse Path - Each incoming packet is tested against the FIB and if the interface - is not the best reverse path the packet check will fail. - By default failed packets are discarded. - 2 - Loose mode as defined in RFC3704 Loose Reverse Path - Each incoming packet's source address is also tested against the FIB - and if the source address is not reachable via any interface - the packet check will fail. + - 0 - No source validation. + - 1 - Strict mode as defined in RFC3704 Strict Reverse Path + Each incoming packet is tested against the FIB and if the interface + is not the best reverse path the packet check will fail. + By default failed packets are discarded. + - 2 - Loose mode as defined in RFC3704 Loose Reverse Path + Each incoming packet's source address is also tested against the FIB + and if the source address is not reachable via any interface + the packet check will fail. Current recommended practice in RFC3704 is to enable strict mode to prevent IP spoofing from DDos attacks. If using asymmetric routing @@ -1265,19 +1416,19 @@ rp_filter - INTEGER in startup scripts. arp_filter - BOOLEAN - 1 - Allows you to have multiple network interfaces on the same - subnet, and have the ARPs for each interface be answered - based on whether or not the kernel would route a packet from - the ARP'd IP out that interface (therefore you must use source - based routing for this to work). In other words it allows control - of which cards (usually 1) will respond to an arp request. + - 1 - Allows you to have multiple network interfaces on the same + subnet, and have the ARPs for each interface be answered + based on whether or not the kernel would route a packet from + the ARP'd IP out that interface (therefore you must use source + based routing for this to work). In other words it allows control + of which cards (usually 1) will respond to an arp request. - 0 - (default) The kernel can respond to arp requests with addresses - from other interfaces. This may seem wrong but it usually makes - sense, because it increases the chance of successful communication. - IP addresses are owned by the complete host on Linux, not by - particular interfaces. Only for more complex setups like load- - balancing, does this behaviour cause problems. + - 0 - (default) The kernel can respond to arp requests with addresses + from other interfaces. This may seem wrong but it usually makes + sense, because it increases the chance of successful communication. + IP addresses are owned by the complete host on Linux, not by + particular interfaces. Only for more complex setups like load- + balancing, does this behaviour cause problems. arp_filter for the interface will be enabled if at least one of conf/{all,interface}/arp_filter is set to TRUE, @@ -1287,26 +1438,27 @@ arp_announce - INTEGER Define different restriction levels for announcing the local source IP address from IP packets in ARP requests sent on interface: - 0 - (default) Use any local address, configured on any interface - 1 - Try to avoid local addresses that are not in the target's - subnet for this interface. This mode is useful when target - hosts reachable via this interface require the source IP - address in ARP requests to be part of their logical network - configured on the receiving interface. When we generate the - request we will check all our subnets that include the - target IP and will preserve the source address if it is from - such subnet. If there is no such subnet we select source - address according to the rules for level 2. - 2 - Always use the best local address for this target. - In this mode we ignore the source address in the IP packet - and try to select local address that we prefer for talks with - the target host. Such local address is selected by looking - for primary IP addresses on all our subnets on the outgoing - interface that include the target IP address. If no suitable - local address is found we select the first local address - we have on the outgoing interface or on all other interfaces, - with the hope we will receive reply for our request and - even sometimes no matter the source IP address we announce. + + - 0 - (default) Use any local address, configured on any interface + - 1 - Try to avoid local addresses that are not in the target's + subnet for this interface. This mode is useful when target + hosts reachable via this interface require the source IP + address in ARP requests to be part of their logical network + configured on the receiving interface. When we generate the + request we will check all our subnets that include the + target IP and will preserve the source address if it is from + such subnet. If there is no such subnet we select source + address according to the rules for level 2. + - 2 - Always use the best local address for this target. + In this mode we ignore the source address in the IP packet + and try to select local address that we prefer for talks with + the target host. Such local address is selected by looking + for primary IP addresses on all our subnets on the outgoing + interface that include the target IP address. If no suitable + local address is found we select the first local address + we have on the outgoing interface or on all other interfaces, + with the hope we will receive reply for our request and + even sometimes no matter the source IP address we announce. The max value from conf/{all,interface}/arp_announce is used. @@ -1317,32 +1469,37 @@ arp_announce - INTEGER arp_ignore - INTEGER Define different modes for sending replies in response to received ARP requests that resolve local target IP addresses: - 0 - (default): reply for any local target IP address, configured - on any interface - 1 - reply only if the target IP address is local address - configured on the incoming interface - 2 - reply only if the target IP address is local address - configured on the incoming interface and both with the - sender's IP address are part from same subnet on this interface - 3 - do not reply for local addresses configured with scope host, - only resolutions for global and link addresses are replied - 4-7 - reserved - 8 - do not reply for all local addresses + + - 0 - (default): reply for any local target IP address, configured + on any interface + - 1 - reply only if the target IP address is local address + configured on the incoming interface + - 2 - reply only if the target IP address is local address + configured on the incoming interface and both with the + sender's IP address are part from same subnet on this interface + - 3 - do not reply for local addresses configured with scope host, + only resolutions for global and link addresses are replied + - 4-7 - reserved + - 8 - do not reply for all local addresses The max value from conf/{all,interface}/arp_ignore is used when ARP request is received on the {interface} arp_notify - BOOLEAN Define mode for notification of address and device changes. - 0 - (default): do nothing - 1 - Generate gratuitous arp requests when device is brought up - or hardware address changes. + + == ========================================================== + 0 (default): do nothing + 1 Generate gratuitous arp requests when device is brought up + or hardware address changes. + == ========================================================== arp_accept - BOOLEAN Define behavior for gratuitous ARP frames who's IP is not already present in the ARP table: - 0 - don't create new entries in the ARP table - 1 - create new entries in the ARP table + + - 0 - don't create new entries in the ARP table + - 1 - create new entries in the ARP table Both replies and requests type gratuitous arp will trigger the ARP table to be updated, if this setting is on. @@ -1378,11 +1535,13 @@ disable_xfrm - BOOLEAN igmpv2_unsolicited_report_interval - INTEGER The interval in milliseconds in which the next unsolicited IGMPv1 or IGMPv2 report retransmit will take place. + Default: 10000 (10 seconds) igmpv3_unsolicited_report_interval - INTEGER The interval in milliseconds in which the next unsolicited IGMPv3 report retransmit will take place. + Default: 1000 (1 seconds) promote_secondaries - BOOLEAN @@ -1393,19 +1552,23 @@ promote_secondaries - BOOLEAN drop_unicast_in_l2_multicast - BOOLEAN Drop any unicast IP packets that are received in link-layer multicast (or broadcast) frames. + This behavior (for multicast) is actually a SHOULD in RFC 1122, but is disabled by default for compatibility reasons. + Default: off (0) drop_gratuitous_arp - BOOLEAN Drop all gratuitous ARP frames, for example if there's a known good ARP proxy on the network and such frames need not be used (or in the case of 802.11, must not be used to prevent attacks.) + Default: off (0) tag - INTEGER Allows you to write a number, which can be used as required. + Default value is 0. xfrm4_gc_thresh - INTEGER @@ -1417,21 +1580,24 @@ xfrm4_gc_thresh - INTEGER igmp_link_local_mcast_reports - BOOLEAN Enable IGMP reports for link local multicast groups in the 224.0.0.X range. + Default TRUE Alexey Kuznetsov. kuznet@ms2.inr.ac.ru Updated by: -Andi Kleen -ak@muc.de -Nicolas Delon -delon.nicolas@wanadoo.fr +- Andi Kleen + ak@muc.de +- Nicolas Delon + delon.nicolas@wanadoo.fr -/proc/sys/net/ipv6/* Variables: + +/proc/sys/net/ipv6/* Variables +============================== IPv6 has no global variables such as tcp_*. tcp_* settings under ipv4/ also apply to IPv6 [XXX?]. @@ -1440,8 +1606,9 @@ bindv6only - BOOLEAN Default value for IPV6_V6ONLY socket option, which restricts use of the IPv6 socket to IPv6 communication only. - TRUE: disable IPv4-mapped address feature - FALSE: enable IPv4-mapped address feature + + - TRUE: disable IPv4-mapped address feature + - FALSE: enable IPv4-mapped address feature Default: FALSE (as specified in RFC3493) @@ -1449,8 +1616,10 @@ flowlabel_consistency - BOOLEAN Protect the consistency (and unicity) of flow label. You have to disable it to use IPV6_FL_F_REFLECT flag on the flow label manager. - TRUE: enabled - FALSE: disabled + + - TRUE: enabled + - FALSE: disabled + Default: TRUE auto_flowlabels - INTEGER @@ -1458,22 +1627,28 @@ auto_flowlabels - INTEGER packet. This allows intermediate devices, such as routers, to identify packet flows for mechanisms like Equal Cost Multipath Routing (see RFC 6438). - 0: automatic flow labels are completely disabled - 1: automatic flow labels are enabled by default, they can be + + = =========================================================== + 0 automatic flow labels are completely disabled + 1 automatic flow labels are enabled by default, they can be disabled on a per socket basis using the IPV6_AUTOFLOWLABEL socket option - 2: automatic flow labels are allowed, they may be enabled on a + 2 automatic flow labels are allowed, they may be enabled on a per socket basis using the IPV6_AUTOFLOWLABEL socket option - 3: automatic flow labels are enabled and enforced, they cannot + 3 automatic flow labels are enabled and enforced, they cannot be disabled by the socket option + = =========================================================== + Default: 1 flowlabel_state_ranges - BOOLEAN Split the flow label number space into two ranges. 0-0x7FFFF is reserved for the IPv6 flow manager facility, 0x80000-0xFFFFF is reserved for stateless flow labels as described in RFC6437. - TRUE: enabled - FALSE: disabled + + - TRUE: enabled + - FALSE: disabled + Default: true flowlabel_reflect - INTEGER @@ -1483,49 +1658,59 @@ flowlabel_reflect - INTEGER https://tools.ietf.org/html/draft-wang-6man-flow-label-reflection-01 This is a bitmask. - 1: enabled for established flows - Note that this prevents automatic flowlabel changes, as done - in "tcp: change IPv6 flow-label upon receiving spurious retransmission" - and "tcp: Change txhash on every SYN and RTO retransmit" + - 1: enabled for established flows - 2: enabled for TCP RESET packets (no active listener) - If set, a RST packet sent in response to a SYN packet on a closed - port will reflect the incoming flow label. + Note that this prevents automatic flowlabel changes, as done + in "tcp: change IPv6 flow-label upon receiving spurious retransmission" + and "tcp: Change txhash on every SYN and RTO retransmit" - 4: enabled for ICMPv6 echo reply messages. + - 2: enabled for TCP RESET packets (no active listener) + If set, a RST packet sent in response to a SYN packet on a closed + port will reflect the incoming flow label. + + - 4: enabled for ICMPv6 echo reply messages. Default: 0 fib_multipath_hash_policy - INTEGER Controls which hash policy to use for multipath routes. + Default: 0 (Layer 3) + Possible values: - 0 - Layer 3 (source and destination addresses plus flow label) - 1 - Layer 4 (standard 5-tuple) - 2 - Layer 3 or inner Layer 3 if present + + - 0 - Layer 3 (source and destination addresses plus flow label) + - 1 - Layer 4 (standard 5-tuple) + - 2 - Layer 3 or inner Layer 3 if present anycast_src_echo_reply - BOOLEAN Controls the use of anycast addresses as source addresses for ICMPv6 echo reply - TRUE: enabled - FALSE: disabled + + - TRUE: enabled + - FALSE: disabled + Default: FALSE idgen_delay - INTEGER Controls the delay in seconds after which time to retry privacy stable address generation if a DAD conflict is detected. + Default: 1 (as specified in RFC7217) idgen_retries - INTEGER Controls the number of retries to generate a stable privacy address if a DAD conflict is detected. + Default: 3 (as specified in RFC7217) mld_qrv - INTEGER Controls the MLD query robustness variable (see RFC3810 9.1). + Default: 2 (as specified by RFC3810 9.1) + Minimum: 1 (as specified by RFC6636 4.5) max_dst_opts_number - INTEGER @@ -1533,6 +1718,7 @@ max_dst_opts_number - INTEGER options extension header. If this value is less than zero then unknown options are disallowed and the number of known TLVs allowed is the absolute value of this number. + Default: 8 max_hbh_opts_number - INTEGER @@ -1540,16 +1726,19 @@ max_hbh_opts_number - INTEGER options extension header. If this value is less than zero then unknown options are disallowed and the number of known TLVs allowed is the absolute value of this number. + Default: 8 max_dst_opts_length - INTEGER Maximum length allowed for a Destination options extension header. + Default: INT_MAX (unlimited) max_hbh_length - INTEGER Maximum length allowed for a Hop-by-Hop options extension header. + Default: INT_MAX (unlimited) skip_notify_on_dev_down - BOOLEAN @@ -1558,6 +1747,7 @@ skip_notify_on_dev_down - BOOLEAN generate this message; IPv6 does by default. Setting this sysctl to true skips the message, making IPv4 and IPv6 on par in relying on userspace caches to track link events and evict routes. + Default: false (generate message) IPv6 Fragmentation: @@ -1580,18 +1770,20 @@ seg6_flowlabel - INTEGER Controls the behaviour of computing the flowlabel of outer IPv6 header in case of SR T.encaps - -1 set flowlabel to zero. - 0 copy flowlabel from Inner packet in case of Inner IPv6 - (Set flowlabel to 0 in case IPv4/L2) - 1 Compute the flowlabel using seg6_make_flowlabel() + == ======================================================= + -1 set flowlabel to zero. + 0 copy flowlabel from Inner packet in case of Inner IPv6 + (Set flowlabel to 0 in case IPv4/L2) + 1 Compute the flowlabel using seg6_make_flowlabel() + == ======================================================= Default is 0. -conf/default/*: +``conf/default/*``: Change the interface-specific default settings. -conf/all/*: +``conf/all/*``: Change all the interface-specific settings. [XXX: Other special features than forwarding?] @@ -1615,9 +1807,10 @@ fwmark_reflect - BOOLEAN associated with a socket for example, TCP RSTs or ICMPv6 echo replies). If unset, these packets have a fwmark of zero. If set, they have the fwmark of the packet they are replying to. + Default: 0 -conf/interface/*: +``conf/interface/*``: Change special settings per interface. The functional behaviour for certain settings is different @@ -1632,31 +1825,40 @@ accept_ra - INTEGER transmitted. Possible values are: - 0 Do not accept Router Advertisements. - 1 Accept Router Advertisements if forwarding is disabled. - 2 Overrule forwarding behaviour. Accept Router Advertisements - even if forwarding is enabled. - Functional default: enabled if local forwarding is disabled. - disabled if local forwarding is enabled. + == =========================================================== + 0 Do not accept Router Advertisements. + 1 Accept Router Advertisements if forwarding is disabled. + 2 Overrule forwarding behaviour. Accept Router Advertisements + even if forwarding is enabled. + == =========================================================== + + Functional default: + + - enabled if local forwarding is disabled. + - disabled if local forwarding is enabled. accept_ra_defrtr - BOOLEAN Learn default router in Router Advertisement. - Functional default: enabled if accept_ra is enabled. - disabled if accept_ra is disabled. + Functional default: + + - enabled if accept_ra is enabled. + - disabled if accept_ra is disabled. accept_ra_from_local - BOOLEAN Accept RA with source-address that is found on local machine - if the RA is otherwise proper and able to be accepted. - Default is to NOT accept these as it may be an un-intended - network loop. + if the RA is otherwise proper and able to be accepted. + + Default is to NOT accept these as it may be an un-intended + network loop. Functional default: - enabled if accept_ra_from_local is enabled - on a specific interface. - disabled if accept_ra_from_local is disabled - on a specific interface. + + - enabled if accept_ra_from_local is enabled + on a specific interface. + - disabled if accept_ra_from_local is disabled + on a specific interface. accept_ra_min_hop_limit - INTEGER Minimum hop limit Information in Router Advertisement. @@ -1669,8 +1871,10 @@ accept_ra_min_hop_limit - INTEGER accept_ra_pinfo - BOOLEAN Learn Prefix Information in Router Advertisement. - Functional default: enabled if accept_ra is enabled. - disabled if accept_ra is disabled. + Functional default: + + - enabled if accept_ra is enabled. + - disabled if accept_ra is disabled. accept_ra_rt_info_min_plen - INTEGER Minimum prefix length of Route Information in RA. @@ -1678,8 +1882,10 @@ accept_ra_rt_info_min_plen - INTEGER Route Information w/ prefix smaller than this variable shall be ignored. - Functional default: 0 if accept_ra_rtr_pref is enabled. - -1 if accept_ra_rtr_pref is disabled. + Functional default: + + * 0 if accept_ra_rtr_pref is enabled. + * -1 if accept_ra_rtr_pref is disabled. accept_ra_rt_info_max_plen - INTEGER Maximum prefix length of Route Information in RA. @@ -1687,33 +1893,41 @@ accept_ra_rt_info_max_plen - INTEGER Route Information w/ prefix larger than this variable shall be ignored. - Functional default: 0 if accept_ra_rtr_pref is enabled. - -1 if accept_ra_rtr_pref is disabled. + Functional default: + + * 0 if accept_ra_rtr_pref is enabled. + * -1 if accept_ra_rtr_pref is disabled. accept_ra_rtr_pref - BOOLEAN Accept Router Preference in RA. - Functional default: enabled if accept_ra is enabled. - disabled if accept_ra is disabled. + Functional default: + + - enabled if accept_ra is enabled. + - disabled if accept_ra is disabled. accept_ra_mtu - BOOLEAN Apply the MTU value specified in RA option 5 (RFC4861). If disabled, the MTU specified in the RA will be ignored. - Functional default: enabled if accept_ra is enabled. - disabled if accept_ra is disabled. + Functional default: + + - enabled if accept_ra is enabled. + - disabled if accept_ra is disabled. accept_redirects - BOOLEAN Accept Redirects. - Functional default: enabled if local forwarding is disabled. - disabled if local forwarding is enabled. + Functional default: + + - enabled if local forwarding is disabled. + - disabled if local forwarding is enabled. accept_source_route - INTEGER Accept source routing (routing extension header). - >= 0: Accept only routing header type 2. - < 0: Do not accept routing header. + - >= 0: Accept only routing header type 2. + - < 0: Do not accept routing header. Default: 0 @@ -1721,24 +1935,30 @@ autoconf - BOOLEAN Autoconfigure addresses using Prefix Information in Router Advertisements. - Functional default: enabled if accept_ra_pinfo is enabled. - disabled if accept_ra_pinfo is disabled. + Functional default: + + - enabled if accept_ra_pinfo is enabled. + - disabled if accept_ra_pinfo is disabled. dad_transmits - INTEGER The amount of Duplicate Address Detection probes to send. + Default: 1 forwarding - INTEGER Configure interface-specific Host/Router behaviour. - Note: It is recommended to have the same setting on all - interfaces; mixed router/host scenarios are rather uncommon. + .. note:: + + It is recommended to have the same setting on all + interfaces; mixed router/host scenarios are rather uncommon. Possible values are: - 0 Forwarding disabled - 1 Forwarding enabled - FALSE (0): + - 0 Forwarding disabled + - 1 Forwarding enabled + + **FALSE (0)**: By default, Host behaviour is assumed. This means: @@ -1749,7 +1969,7 @@ forwarding - INTEGER Advertisements (and do autoconfiguration). 4. If accept_redirects is TRUE (default), accept Redirects. - TRUE (1): + **TRUE (1)**: If local forwarding is enabled, Router behaviour is assumed. This means exactly the reverse from the above: @@ -1760,19 +1980,22 @@ forwarding - INTEGER 4. Redirects are ignored. Default: 0 (disabled) if global forwarding is disabled (default), - otherwise 1 (enabled). + otherwise 1 (enabled). hop_limit - INTEGER Default Hop Limit to set. + Default: 64 mtu - INTEGER Default Maximum Transfer Unit + Default: 1280 (IPv6 required minimum) ip_nonlocal_bind - BOOLEAN If set, allows processes to bind() to non-local IPv6 addresses, which can be quite useful - but may break some applications. + Default: 0 router_probe_interval - INTEGER @@ -1784,15 +2007,18 @@ router_probe_interval - INTEGER router_solicitation_delay - INTEGER Number of seconds to wait after interface is brought up before sending Router Solicitations. + Default: 1 router_solicitation_interval - INTEGER Number of seconds to wait between Router Solicitations. + Default: 4 router_solicitations - INTEGER Number of Router Solicitations to send until assuming no routers are present. + Default: 3 use_oif_addrs_only - BOOLEAN @@ -1804,28 +2030,35 @@ use_oif_addrs_only - BOOLEAN use_tempaddr - INTEGER Preference for Privacy Extensions (RFC3041). - <= 0 : disable Privacy Extensions - == 1 : enable Privacy Extensions, but prefer public - addresses over temporary addresses. - > 1 : enable Privacy Extensions and prefer temporary - addresses over public addresses. - Default: 0 (for most devices) - -1 (for point-to-point devices and loopback devices) + + * <= 0 : disable Privacy Extensions + * == 1 : enable Privacy Extensions, but prefer public + addresses over temporary addresses. + * > 1 : enable Privacy Extensions and prefer temporary + addresses over public addresses. + + Default: + + * 0 (for most devices) + * -1 (for point-to-point devices and loopback devices) temp_valid_lft - INTEGER valid lifetime (in seconds) for temporary addresses. + Default: 604800 (7 days) temp_prefered_lft - INTEGER Preferred lifetime (in seconds) for temporary addresses. + Default: 86400 (1 day) keep_addr_on_down - INTEGER Keep all IPv6 addresses on an interface down event. If set static global addresses with no expiration time are not flushed. - >0 : enabled - 0 : system default - <0 : disabled + + * >0 : enabled + * 0 : system default + * <0 : disabled Default: 0 (addresses are removed) @@ -1834,11 +2067,13 @@ max_desync_factor - INTEGER that ensures that clients don't synchronize with each other and generate new addresses at exactly the same time. value is in seconds. + Default: 600 regen_max_retry - INTEGER Number of attempts before give up attempting to generate valid temporary addresses. + Default: 5 max_addresses - INTEGER @@ -1846,12 +2081,14 @@ max_addresses - INTEGER to zero disables the limitation. It is not recommended to set this value too large (or to zero) because it would be an easy way to crash the kernel by allowing too many addresses to be created. + Default: 16 disable_ipv6 - BOOLEAN Disable IPv6 operation. If accept_dad is set to 2, this value will be dynamically set to TRUE if DAD fails for the link-local address. + Default: FALSE (enable IPv6 operation) When this value is changed from 1 to 0 (IPv6 is being enabled), @@ -1865,10 +2102,13 @@ disable_ipv6 - BOOLEAN accept_dad - INTEGER Whether to accept DAD (Duplicate Address Detection). - 0: Disable DAD - 1: Enable DAD (default) - 2: Enable DAD, and disable IPv6 operation if MAC-based duplicate - link-local address has been found. + + == ============================================================== + 0 Disable DAD + 1 Enable DAD (default) + 2 Enable DAD, and disable IPv6 operation if MAC-based duplicate + link-local address has been found. + == ============================================================== DAD operation and mode on a given interface will be selected according to the maximum value of conf/{all,interface}/accept_dad. @@ -1876,6 +2116,7 @@ accept_dad - INTEGER force_tllao - BOOLEAN Enable sending the target link-layer address option even when responding to a unicast neighbor solicitation. + Default: FALSE Quoting from RFC 2461, section 4.4, Target link-layer address: @@ -1893,9 +2134,10 @@ force_tllao - BOOLEAN ndisc_notify - BOOLEAN Define mode for notification of address and device changes. - 0 - (default): do nothing - 1 - Generate unsolicited neighbour advertisements when device is brought - up or hardware address changes. + + * 0 - (default): do nothing + * 1 - Generate unsolicited neighbour advertisements when device is brought + up or hardware address changes. ndisc_tclass - INTEGER The IPv6 Traffic Class to use by default when sending IPv6 Neighbor @@ -1904,33 +2146,38 @@ ndisc_tclass - INTEGER These 8 bits can be interpreted as 6 high order bits holding the DSCP value and 2 low order bits representing ECN (which you probably want to leave cleared). - 0 - (default) + + * 0 - (default) mldv1_unsolicited_report_interval - INTEGER The interval in milliseconds in which the next unsolicited MLDv1 report retransmit will take place. + Default: 10000 (10 seconds) mldv2_unsolicited_report_interval - INTEGER The interval in milliseconds in which the next unsolicited MLDv2 report retransmit will take place. + Default: 1000 (1 second) force_mld_version - INTEGER - 0 - (default) No enforcement of a MLD version, MLDv1 fallback allowed - 1 - Enforce to use MLD version 1 - 2 - Enforce to use MLD version 2 + * 0 - (default) No enforcement of a MLD version, MLDv1 fallback allowed + * 1 - Enforce to use MLD version 1 + * 2 - Enforce to use MLD version 2 suppress_frag_ndisc - INTEGER Control RFC 6980 (Security Implications of IPv6 Fragmentation with IPv6 Neighbor Discovery) behavior: - 1 - (default) discard fragmented neighbor discovery packets - 0 - allow fragmented neighbor discovery packets + + * 1 - (default) discard fragmented neighbor discovery packets + * 0 - allow fragmented neighbor discovery packets optimistic_dad - BOOLEAN Whether to perform Optimistic Duplicate Address Detection (RFC 4429). - 0: disabled (default) - 1: enabled + + * 0: disabled (default) + * 1: enabled Optimistic Duplicate Address Detection for the interface will be enabled if at least one of conf/{all,interface}/optimistic_dad is set to 1, @@ -1941,8 +2188,9 @@ use_optimistic - BOOLEAN source address selection. Preferred addresses will still be chosen before optimistic addresses, subject to other ranking in the source address selection algorithm. - 0: disabled (default) - 1: enabled + + * 0: disabled (default) + * 1: enabled This will be enabled if at least one of conf/{all,interface}/use_optimistic is set to 1, disabled otherwise. @@ -1964,12 +2212,14 @@ stable_secret - IPv6 address addr_gen_mode - INTEGER Defines how link-local and autoconf addresses are generated. - 0: generate address based on EUI64 (default) - 1: do no generate a link-local address, use EUI64 for addresses generated - from autoconf - 2: generate stable privacy addresses, using the secret from + = ================================================================= + 0 generate address based on EUI64 (default) + 1 do no generate a link-local address, use EUI64 for addresses + generated from autoconf + 2 generate stable privacy addresses, using the secret from stable_secret (RFC7217) - 3: generate stable privacy addresses, using a random secret if unset + 3 generate stable privacy addresses, using a random secret if unset + = ================================================================= drop_unicast_in_l2_multicast - BOOLEAN Drop any unicast IPv6 packets that are received in link-layer @@ -1991,13 +2241,18 @@ enhanced_dad - BOOLEAN detection of duplicates due to loopback of the NS messages that we send. The nonce option will be sent on an interface unless both of conf/{all,interface}/enhanced_dad are set to FALSE. + Default: TRUE -icmp/*: +``icmp/*``: +=========== + ratelimit - INTEGER Limit the maximal rates for sending ICMPv6 messages. + 0 to disable any limiting, otherwise the minimal space between responses in milliseconds. + Default: 1000 ratemask - list of comma separated ranges @@ -2018,16 +2273,19 @@ ratemask - list of comma separated ranges echo_ignore_all - BOOLEAN If set non-zero, then the kernel will ignore all ICMP ECHO requests sent to it over the IPv6 protocol. + Default: 0 echo_ignore_multicast - BOOLEAN If set non-zero, then the kernel will ignore all ICMP ECHO requests sent to it over the IPv6 protocol via multicast. + Default: 0 echo_ignore_anycast - BOOLEAN If set non-zero, then the kernel will ignore all ICMP ECHO requests sent to it over the IPv6 protocol destined to anycast address. + Default: 0 xfrm6_gc_thresh - INTEGER @@ -2043,43 +2301,52 @@ YOSHIFUJI Hideaki / USAGI Project /proc/sys/net/bridge/* Variables: +================================= bridge-nf-call-arptables - BOOLEAN - 1 : pass bridged ARP traffic to arptables' FORWARD chain. - 0 : disable this. + - 1 : pass bridged ARP traffic to arptables' FORWARD chain. + - 0 : disable this. + Default: 1 bridge-nf-call-iptables - BOOLEAN - 1 : pass bridged IPv4 traffic to iptables' chains. - 0 : disable this. + - 1 : pass bridged IPv4 traffic to iptables' chains. + - 0 : disable this. + Default: 1 bridge-nf-call-ip6tables - BOOLEAN - 1 : pass bridged IPv6 traffic to ip6tables' chains. - 0 : disable this. + - 1 : pass bridged IPv6 traffic to ip6tables' chains. + - 0 : disable this. + Default: 1 bridge-nf-filter-vlan-tagged - BOOLEAN - 1 : pass bridged vlan-tagged ARP/IP/IPv6 traffic to {arp,ip,ip6}tables. - 0 : disable this. + - 1 : pass bridged vlan-tagged ARP/IP/IPv6 traffic to {arp,ip,ip6}tables. + - 0 : disable this. + Default: 0 bridge-nf-filter-pppoe-tagged - BOOLEAN - 1 : pass bridged pppoe-tagged IP/IPv6 traffic to {ip,ip6}tables. - 0 : disable this. + - 1 : pass bridged pppoe-tagged IP/IPv6 traffic to {ip,ip6}tables. + - 0 : disable this. + Default: 0 bridge-nf-pass-vlan-input-dev - BOOLEAN - 1: if bridge-nf-filter-vlan-tagged is enabled, try to find a vlan - interface on the bridge and set the netfilter input device to the vlan. - This allows use of e.g. "iptables -i br0.1" and makes the REDIRECT - target work with vlan-on-top-of-bridge interfaces. When no matching - vlan interface is found, or this switch is off, the input device is - set to the bridge interface. - 0: disable bridge netfilter vlan interface lookup. + - 1: if bridge-nf-filter-vlan-tagged is enabled, try to find a vlan + interface on the bridge and set the netfilter input device to the + vlan. This allows use of e.g. "iptables -i br0.1" and makes the + REDIRECT target work with vlan-on-top-of-bridge interfaces. When no + matching vlan interface is found, or this switch is off, the input + device is set to the bridge interface. + + - 0: disable bridge netfilter vlan interface lookup. + Default: 0 -proc/sys/net/sctp/* Variables: +``proc/sys/net/sctp/*`` Variables: +================================== addip_enable - BOOLEAN Enable or disable extension of Dynamic Address Reconfiguration @@ -2144,11 +2411,13 @@ addip_noauth_enable - BOOLEAN we provide this variable to control the enforcement of the authentication requirement. - 1: Allow ADD-IP extension to be used without authentication. This + == =============================================================== + 1 Allow ADD-IP extension to be used without authentication. This should only be set in a closed environment for interoperability with older implementations. - 0: Enforce the authentication requirement + 0 Enforce the authentication requirement + == =============================================================== Default: 0 @@ -2158,8 +2427,8 @@ auth_enable - BOOLEAN required for secure operation of Dynamic Address Reconfiguration (ADD-IP) extension. - 1: Enable this extension. - 0: Disable this extension. + - 1: Enable this extension. + - 0: Disable this extension. Default: 0 @@ -2167,8 +2436,8 @@ prsctp_enable - BOOLEAN Enable or disable the Partial Reliability extension (RFC3758) which is used to notify peers that a given DATA should no longer be expected. - 1: Enable extension - 0: Disable + - 1: Enable extension + - 0: Disable Default: 1 @@ -2270,8 +2539,8 @@ cookie_preserve_enable - BOOLEAN Enable or disable the ability to extend the lifetime of the SCTP cookie that is used during the establishment phase of SCTP association - 1: Enable cookie lifetime extension. - 0: Disable + - 1: Enable cookie lifetime extension. + - 0: Disable Default: 1 @@ -2279,9 +2548,11 @@ cookie_hmac_alg - STRING Select the hmac algorithm used when generating the cookie value sent by a listening sctp socket to a connecting client in the INIT-ACK chunk. Valid values are: + * md5 * sha1 * none + Ability to assign md5 or sha1 as the selected alg is predicated on the configuration of those algorithms at build time (CONFIG_CRYPTO_MD5 and CONFIG_CRYPTO_SHA1). @@ -2300,16 +2571,16 @@ rcvbuf_policy - INTEGER to each association instead of the socket. This prevents the described blocking. - 1: rcvbuf space is per association - 0: rcvbuf space is per socket + - 1: rcvbuf space is per association + - 0: rcvbuf space is per socket Default: 0 sndbuf_policy - INTEGER Similar to rcvbuf_policy above, this applies to send buffer space. - 1: Send buffer is tracked per association - 0: Send buffer is tracked per socket. + - 1: Send buffer is tracked per association + - 0: Send buffer is tracked per socket. Default: 0 @@ -2342,19 +2613,23 @@ sctp_wmem - vector of 3 INTEGERs: min, default, max addr_scope_policy - INTEGER Control IPv4 address scoping - draft-stewart-tsvwg-sctp-ipv4-00 - 0 - Disable IPv4 address scoping - 1 - Enable IPv4 address scoping - 2 - Follow draft but allow IPv4 private addresses - 3 - Follow draft but allow IPv4 link local addresses + - 0 - Disable IPv4 address scoping + - 1 - Enable IPv4 address scoping + - 2 - Follow draft but allow IPv4 private addresses + - 3 - Follow draft but allow IPv4 link local addresses Default: 1 -/proc/sys/net/core/* +``/proc/sys/net/core/*`` +======================== + Please see: Documentation/admin-guide/sysctl/net.rst for descriptions of these entries. -/proc/sys/net/unix/* +``/proc/sys/net/unix/*`` +======================== + max_dgram_qlen - INTEGER The maximum length of dgram socket receive queue diff --git a/Documentation/networking/snmp_counter.rst b/Documentation/networking/snmp_counter.rst index 10e11099e74a..4edd0d38779e 100644 --- a/Documentation/networking/snmp_counter.rst +++ b/Documentation/networking/snmp_counter.rst @@ -792,7 +792,7 @@ counters to indicate the ACK is skipped in which scenario. The ACK would only be skipped if the received packet is either a SYN packet or it has no data. -.. _sysctl document: https://www.kernel.org/doc/Documentation/networking/ip-sysctl.txt +.. _sysctl document: https://www.kernel.org/doc/Documentation/networking/ip-sysctl.rst * TcpExtTCPACKSkippedSynRecv diff --git a/net/Kconfig b/net/Kconfig index df8d8c9bd021..8b1f85820a6b 100644 --- a/net/Kconfig +++ b/net/Kconfig @@ -86,7 +86,7 @@ config INET "Sysctl support" below, you can change various aspects of the behavior of the TCP/IP code by writing to the (virtual) files in /proc/sys/net/ipv4/*; the options are explained in the file - . + . Short answer: say Y. diff --git a/net/ipv4/Kconfig b/net/ipv4/Kconfig index 25a8888826b8..5da4733067fb 100644 --- a/net/ipv4/Kconfig +++ b/net/ipv4/Kconfig @@ -49,7 +49,7 @@ config IP_ADVANCED_ROUTER Note that some distributions enable it in startup scripts. For details about rp_filter strict and loose mode read - . + . If unsure, say N here. diff --git a/net/ipv4/icmp.c b/net/ipv4/icmp.c index fc61f51d87a3..956a806649f7 100644 --- a/net/ipv4/icmp.c +++ b/net/ipv4/icmp.c @@ -853,7 +853,7 @@ static bool icmp_unreach(struct sk_buff *skb) case ICMP_FRAG_NEEDED: /* for documentation of the ip_no_pmtu_disc * values please see - * Documentation/networking/ip-sysctl.txt + * Documentation/networking/ip-sysctl.rst */ switch (net->ipv4.sysctl_ip_no_pmtu_disc) { default: From patchwork Mon Apr 27 22:01:51 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Mauro Carvalho Chehab X-Patchwork-Id: 220455 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-10.1 required=3.0 tests=DKIMWL_WL_HIGH, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, INCLUDES_PATCH, MAILING_LIST_MULTI, SIGNED_OFF_BY, SPF_HELO_NONE, SPF_PASS, USER_AGENT_GIT autolearn=ham autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 7F664C82A03 for ; Mon, 27 Apr 2020 22:03:01 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 522D62082E for ; Mon, 27 Apr 2020 22:03:01 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1588024981; bh=5GyocPN1j5lv+FlYwDsdmatxNKvxZCH0LYtt/TFNhhU=; h=From:To:Cc:Subject:Date:In-Reply-To:References:List-ID:From; b=KAFSGZCfsDJ9bPA9Ibs90M7/0v1V4Jx4Mahwo/4O7f0AXy/wjTNCYzEoiKP1lfc7I 7zD5t9CMbgFex//Z6eev0n30mxdYoEZD0qdEL5rtaNKmKB38MXvz/BUYa3DHfYNtkj eBzVP7Lac0Qoj1RupKF2t2XxxOm+RdnbR+ZP9C7U= Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1726617AbgD0WDA (ORCPT ); Mon, 27 Apr 2020 18:03:00 -0400 Received: from mail.kernel.org ([198.145.29.99]:48024 "EHLO mail.kernel.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726403AbgD0WCB (ORCPT ); Mon, 27 Apr 2020 18:02:01 -0400 Received: from mail.kernel.org (ip5f5ad5c5.dynamic.kabel-deutschland.de [95.90.213.197]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPSA id 28F9222280; Mon, 27 Apr 2020 22:01:57 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1588024917; bh=5GyocPN1j5lv+FlYwDsdmatxNKvxZCH0LYtt/TFNhhU=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=oh2ate4wURDvTDDXt26LKpbjvn01L/GWdFZX11gJcr8y3xr2LxEdDQiWU1ay+P/+o rn+JXzbV26AJIbxtH1WyN3uckUliFSdpPN8UHwNnXbxW6HaHsqquDcn1Hk1coxUQV1 yG4PFHHdmiZL8gQ55wx1ZjO5OxbYx+DbJfjNErZ0= Received: from mchehab by mail.kernel.org with local (Exim 4.92.3) (envelope-from ) id 1jTBp5-000IqW-ES; Tue, 28 Apr 2020 00:01:55 +0200 From: Mauro Carvalho Chehab To: Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Jonathan Corbet , "David S. Miller" , Jakub Kicinski , netdev@vger.kernel.org Subject: [PATCH 36/38] docs: networking: convert ipvlan.txt to ReST Date: Tue, 28 Apr 2020 00:01:51 +0200 Message-Id: X-Mailer: git-send-email 2.25.4 In-Reply-To: References: MIME-Version: 1.0 Sender: netdev-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: netdev@vger.kernel.org - add SPDX header; - adjust titles and chapters, adding proper markups; - mark code blocks and literals as such; - adjust identation, whitespaces and blank lines; - add to networking/index.rst. Signed-off-by: Mauro Carvalho Chehab --- Documentation/networking/index.rst | 1 + .../networking/{ipvlan.txt => ipvlan.rst} | 159 +++++++++++------- 2 files changed, 102 insertions(+), 58 deletions(-) rename Documentation/networking/{ipvlan.txt => ipvlan.rst} (54%) diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst index 709675464e51..54dee1575b54 100644 --- a/Documentation/networking/index.rst +++ b/Documentation/networking/index.rst @@ -71,6 +71,7 @@ Contents: ipsec ip-sysctl ipv6 + ipvlan .. only:: subproject and html diff --git a/Documentation/networking/ipvlan.txt b/Documentation/networking/ipvlan.rst similarity index 54% rename from Documentation/networking/ipvlan.txt rename to Documentation/networking/ipvlan.rst index 27a38e50c287..694adcba36b0 100644 --- a/Documentation/networking/ipvlan.txt +++ b/Documentation/networking/ipvlan.rst @@ -1,11 +1,15 @@ +.. SPDX-License-Identifier: GPL-2.0 - IPVLAN Driver HOWTO +=================== +IPVLAN Driver HOWTO +=================== Initial Release: Mahesh Bandewar 1. Introduction: - This is conceptually very similar to the macvlan driver with one major +================ +This is conceptually very similar to the macvlan driver with one major exception of using L3 for mux-ing /demux-ing among slaves. This property makes the master device share the L2 with it's slave devices. I have developed this driver in conjunction with network namespaces and not sure if there is use case @@ -13,34 +17,48 @@ outside of it. 2. Building and Installation: - In order to build the driver, please select the config item CONFIG_IPVLAN. +============================= + +In order to build the driver, please select the config item CONFIG_IPVLAN. The driver can be built into the kernel (CONFIG_IPVLAN=y) or as a module (CONFIG_IPVLAN=m). 3. Configuration: - There are no module parameters for this driver and it can be configured +================= + +There are no module parameters for this driver and it can be configured using IProute2/ip utility. +:: ip link add link name type ipvlan [ mode MODE ] [ FLAGS ] where - MODE: l3 (default) | l3s | l2 - FLAGS: bridge (default) | private | vepa + MODE: l3 (default) | l3s | l2 + FLAGS: bridge (default) | private | vepa + +e.g. - e.g. (a) Following will create IPvlan link with eth0 as master in - L3 bridge mode - bash# ip link add link eth0 name ipvl0 type ipvlan - (b) This command will create IPvlan link in L2 bridge mode. - bash# ip link add link eth0 name ipvl0 type ipvlan mode l2 bridge - (c) This command will create an IPvlan device in L2 private mode. - bash# ip link add link eth0 name ipvlan type ipvlan mode l2 private - (d) This command will create an IPvlan device in L2 vepa mode. - bash# ip link add link eth0 name ipvlan type ipvlan mode l2 vepa + L3 bridge mode:: + + bash# ip link add link eth0 name ipvl0 type ipvlan + (b) This command will create IPvlan link in L2 bridge mode:: + + bash# ip link add link eth0 name ipvl0 type ipvlan mode l2 bridge + + (c) This command will create an IPvlan device in L2 private mode:: + + bash# ip link add link eth0 name ipvlan type ipvlan mode l2 private + + (d) This command will create an IPvlan device in L2 vepa mode:: + + bash# ip link add link eth0 name ipvlan type ipvlan mode l2 vepa 4. Operating modes: - IPvlan has two modes of operation - L2 and L3. For a given master device, +=================== + +IPvlan has two modes of operation - L2 and L3. For a given master device, you can select one of these two modes and all slaves on that master will operate in the same (selected) mode. The RX mode is almost identical except that in L3 mode the slaves wont receive any multicast / broadcast traffic. @@ -48,39 +66,50 @@ L3 mode is more restrictive since routing is controlled from the other (mostly) default namespace. 4.1 L2 mode: - In this mode TX processing happens on the stack instance attached to the +------------ + +In this mode TX processing happens on the stack instance attached to the slave device and packets are switched and queued to the master device to send out. In this mode the slaves will RX/TX multicast and broadcast (if applicable) as well. 4.2 L3 mode: - In this mode TX processing up to L3 happens on the stack instance attached +------------ + +In this mode TX processing up to L3 happens on the stack instance attached to the slave device and packets are switched to the stack instance of the master device for the L2 processing and routing from that instance will be used before packets are queued on the outbound device. In this mode the slaves will not receive nor can send multicast / broadcast traffic. 4.3 L3S mode: - This is very similar to the L3 mode except that iptables (conn-tracking) +------------- + +This is very similar to the L3 mode except that iptables (conn-tracking) works in this mode and hence it is L3-symmetric (L3s). This will have slightly less performance but that shouldn't matter since you are choosing this mode over plain-L3 mode to make conn-tracking work. 5. Mode flags: - At this time following mode flags are available +============== + +At this time following mode flags are available 5.1 bridge: - This is the default option. To configure the IPvlan port in this mode, +----------- +This is the default option. To configure the IPvlan port in this mode, user can choose to either add this option on the command-line or don't specify anything. This is the traditional mode where slaves can cross-talk among themselves apart from talking through the master device. 5.2 private: - If this option is added to the command-line, the port is set in private +------------ +If this option is added to the command-line, the port is set in private mode. i.e. port won't allow cross communication between slaves. 5.3 vepa: - If this is added to the command-line, the port is set in VEPA mode. +--------- +If this is added to the command-line, the port is set in VEPA mode. i.e. port will offload switching functionality to the external entity as described in 802.1Qbg Note: VEPA mode in IPvlan has limitations. IPvlan uses the mac-address of the @@ -89,18 +118,25 @@ neighbor will have source and destination mac same. This will make the switch / router send the redirect message. 6. What to choose (macvlan vs. ipvlan)? - These two devices are very similar in many regards and the specific use +======================================= + +These two devices are very similar in many regards and the specific use case could very well define which device to choose. if one of the following -situations defines your use case then you can choose to use ipvlan - - (a) The Linux host that is connected to the external switch / router has -policy configured that allows only one mac per port. - (b) No of virtual devices created on a master exceed the mac capacity and -puts the NIC in promiscuous mode and degraded performance is a concern. - (c) If the slave device is to be put into the hostile / untrusted network -namespace where L2 on the slave could be changed / misused. +situations defines your use case then you can choose to use ipvlan: + + +(a) The Linux host that is connected to the external switch / router has + policy configured that allows only one mac per port. +(b) No of virtual devices created on a master exceed the mac capacity and + puts the NIC in promiscuous mode and degraded performance is a concern. +(c) If the slave device is to be put into the hostile / untrusted network + namespace where L2 on the slave could be changed / misused. 6. Example configuration: +========================= + +:: +=============================================================+ | Host: host1 | @@ -117,30 +153,37 @@ namespace where L2 on the slave could be changed / misused. +==============================#==============================+ - (a) Create two network namespaces - ns0, ns1 - ip netns add ns0 - ip netns add ns1 - - (b) Create two ipvlan slaves on eth0 (master device) - ip link add link eth0 ipvl0 type ipvlan mode l2 - ip link add link eth0 ipvl1 type ipvlan mode l2 - - (c) Assign slaves to the respective network namespaces - ip link set dev ipvl0 netns ns0 - ip link set dev ipvl1 netns ns1 - - (d) Now switch to the namespace (ns0 or ns1) to configure the slave devices - - For ns0 - (1) ip netns exec ns0 bash - (2) ip link set dev ipvl0 up - (3) ip link set dev lo up - (4) ip -4 addr add 127.0.0.1 dev lo - (5) ip -4 addr add $IPADDR dev ipvl0 - (6) ip -4 route add default via $ROUTER dev ipvl0 - - For ns1 - (1) ip netns exec ns1 bash - (2) ip link set dev ipvl1 up - (3) ip link set dev lo up - (4) ip -4 addr add 127.0.0.1 dev lo - (5) ip -4 addr add $IPADDR dev ipvl1 - (6) ip -4 route add default via $ROUTER dev ipvl1 +(a) Create two network namespaces - ns0, ns1:: + + ip netns add ns0 + ip netns add ns1 + +(b) Create two ipvlan slaves on eth0 (master device):: + + ip link add link eth0 ipvl0 type ipvlan mode l2 + ip link add link eth0 ipvl1 type ipvlan mode l2 + +(c) Assign slaves to the respective network namespaces:: + + ip link set dev ipvl0 netns ns0 + ip link set dev ipvl1 netns ns1 + +(d) Now switch to the namespace (ns0 or ns1) to configure the slave devices + + - For ns0:: + + (1) ip netns exec ns0 bash + (2) ip link set dev ipvl0 up + (3) ip link set dev lo up + (4) ip -4 addr add 127.0.0.1 dev lo + (5) ip -4 addr add $IPADDR dev ipvl0 + (6) ip -4 route add default via $ROUTER dev ipvl0 + + - For ns1:: + + (1) ip netns exec ns1 bash + (2) ip link set dev ipvl1 up + (3) ip link set dev lo up + (4) ip -4 addr add 127.0.0.1 dev lo + (5) ip -4 addr add $IPADDR dev ipvl1 + (6) ip -4 route add default via $ROUTER dev ipvl1 From patchwork Mon Apr 27 22:01:52 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Mauro Carvalho Chehab X-Patchwork-Id: 220459 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-15.1 required=3.0 tests=DKIMWL_WL_HIGH, DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,INCLUDES_PATCH,MAILING_LIST_MULTI, MENTIONS_GIT_HOSTING, SIGNED_OFF_BY, SPF_HELO_NONE, SPF_PASS, USER_AGENT_GIT autolearn=ham autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id BF19FC81857 for ; Mon, 27 Apr 2020 22:02:04 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 8E31B208FE for ; Mon, 27 Apr 2020 22:02:04 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1588024924; bh=clatlTN0Gmh6kZKnYzgXna/TzQHo+XKI58OeJwCd7oY=; h=From:To:Cc:Subject:Date:In-Reply-To:References:List-ID:From; b=VSOpczh1+bVnRKHOm4CtRO/DYlnmpVdX1u/mzO3FHvsnqRTTLP5b6IhBWqEEgj66f Kaqvl+rpxjIZTXWxiuDWsDZINc0ySggts2gs/7W5NYdRh3tD4K8vkQY8rDoicf2nkH jwFsAK7L8wrynmYhUHVe/5rFhnvC1TWR/bQEHf7Q= Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1726458AbgD0WCD (ORCPT ); Mon, 27 Apr 2020 18:02:03 -0400 Received: from mail.kernel.org ([198.145.29.99]:48164 "EHLO mail.kernel.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726410AbgD0WCC (ORCPT ); Mon, 27 Apr 2020 18:02:02 -0400 Received: from mail.kernel.org (ip5f5ad5c5.dynamic.kabel-deutschland.de [95.90.213.197]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPSA id 33F1022286; Mon, 27 Apr 2020 22:01:57 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1588024917; bh=clatlTN0Gmh6kZKnYzgXna/TzQHo+XKI58OeJwCd7oY=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=VsmpCMnO3CqltjMIeFcgFnlLI3DmQESHwE9kRvejGcFNgtbjaA0t8rKYYz37+7qU5 RW81GyzeteeCiJYO2WwJR9GjrxoPv/GvzLBZl1NyXUseNjVIUoUTU9X65pp7DUT5pE A7EOG/wGFuEEecTKXdzAo9snnha9WRH8n/aXNN8s= Received: from mchehab by mail.kernel.org with local (Exim 4.92.3) (envelope-from ) id 1jTBp5-000Iqb-FH; Tue, 28 Apr 2020 00:01:55 +0200 From: Mauro Carvalho Chehab To: Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Jonathan Corbet , "David S. Miller" , Jakub Kicinski , Wensong Zhang , Simon Horman , Julian Anastasov , netdev@vger.kernel.org, lvs-devel@vger.kernel.org Subject: [PATCH 37/38] docs: networking: convert ipvs-sysctl.txt to ReST Date: Tue, 28 Apr 2020 00:01:52 +0200 Message-Id: X-Mailer: git-send-email 2.25.4 In-Reply-To: References: MIME-Version: 1.0 Sender: netdev-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: netdev@vger.kernel.org - add SPDX header; - add a document title; - mark lists as such; - mark code blocks and literals as such; - adjust identation, whitespaces and blank lines; - add to networking/index.rst. Signed-off-by: Mauro Carvalho Chehab --- Documentation/admin-guide/sysctl/net.rst | 4 +- Documentation/networking/index.rst | 1 + .../{ipvs-sysctl.txt => ipvs-sysctl.rst} | 180 +++++++++--------- MAINTAINERS | 2 +- 4 files changed, 98 insertions(+), 89 deletions(-) rename Documentation/networking/{ipvs-sysctl.txt => ipvs-sysctl.rst} (62%) diff --git a/Documentation/admin-guide/sysctl/net.rst b/Documentation/admin-guide/sysctl/net.rst index 84e3348a9543..2ad1b77a7182 100644 --- a/Documentation/admin-guide/sysctl/net.rst +++ b/Documentation/admin-guide/sysctl/net.rst @@ -353,8 +353,8 @@ socket's buffer. It will not take effect unless PF_UNIX flag is specified. 3. /proc/sys/net/ipv4 - IPV4 settings ------------------------------------- -Please see: Documentation/networking/ip-sysctl.rst and ipvs-sysctl.txt for -descriptions of these entries. +Please see: Documentation/networking/ip-sysctl.rst and +Documentation/admin-guide/sysctl/net.rst for descriptions of these entries. 4. Appletalk diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst index 54dee1575b54..bbd4e0041457 100644 --- a/Documentation/networking/index.rst +++ b/Documentation/networking/index.rst @@ -72,6 +72,7 @@ Contents: ip-sysctl ipv6 ipvlan + ipvs-sysctl .. only:: subproject and html diff --git a/Documentation/networking/ipvs-sysctl.txt b/Documentation/networking/ipvs-sysctl.rst similarity index 62% rename from Documentation/networking/ipvs-sysctl.txt rename to Documentation/networking/ipvs-sysctl.rst index 056898685d40..be36c4600e8f 100644 --- a/Documentation/networking/ipvs-sysctl.txt +++ b/Documentation/networking/ipvs-sysctl.rst @@ -1,23 +1,30 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=========== +IPvs-sysctl +=========== + /proc/sys/net/ipv4/vs/* Variables: +================================== am_droprate - INTEGER - default 10 + default 10 - It sets the always mode drop rate, which is used in the mode 3 - of the drop_rate defense. + It sets the always mode drop rate, which is used in the mode 3 + of the drop_rate defense. amemthresh - INTEGER - default 1024 + default 1024 - It sets the available memory threshold (in pages), which is - used in the automatic modes of defense. When there is no - enough available memory, the respective strategy will be - enabled and the variable is automatically set to 2, otherwise - the strategy is disabled and the variable is set to 1. + It sets the available memory threshold (in pages), which is + used in the automatic modes of defense. When there is no + enough available memory, the respective strategy will be + enabled and the variable is automatically set to 2, otherwise + the strategy is disabled and the variable is set to 1. backup_only - BOOLEAN - 0 - disabled (default) - not 0 - enabled + - 0 - disabled (default) + - not 0 - enabled If set, disable the director function while the server is in backup mode to avoid packet loops for DR/TUN methods. @@ -44,8 +51,8 @@ conn_reuse_mode - INTEGER real servers to a very busy cluster. conntrack - BOOLEAN - 0 - disabled (default) - not 0 - enabled + - 0 - disabled (default) + - not 0 - enabled If set, maintain connection tracking entries for connections handled by IPVS. @@ -61,28 +68,28 @@ conntrack - BOOLEAN Only available when IPVS is compiled with CONFIG_IP_VS_NFCT enabled. cache_bypass - BOOLEAN - 0 - disabled (default) - not 0 - enabled + - 0 - disabled (default) + - not 0 - enabled - If it is enabled, forward packets to the original destination - directly when no cache server is available and destination - address is not local (iph->daddr is RTN_UNICAST). It is mostly - used in transparent web cache cluster. + If it is enabled, forward packets to the original destination + directly when no cache server is available and destination + address is not local (iph->daddr is RTN_UNICAST). It is mostly + used in transparent web cache cluster. debug_level - INTEGER - 0 - transmission error messages (default) - 1 - non-fatal error messages - 2 - configuration - 3 - destination trash - 4 - drop entry - 5 - service lookup - 6 - scheduling - 7 - connection new/expire, lookup and synchronization - 8 - state transition - 9 - binding destination, template checks and applications - 10 - IPVS packet transmission - 11 - IPVS packet handling (ip_vs_in/ip_vs_out) - 12 or more - packet traversal + - 0 - transmission error messages (default) + - 1 - non-fatal error messages + - 2 - configuration + - 3 - destination trash + - 4 - drop entry + - 5 - service lookup + - 6 - scheduling + - 7 - connection new/expire, lookup and synchronization + - 8 - state transition + - 9 - binding destination, template checks and applications + - 10 - IPVS packet transmission + - 11 - IPVS packet handling (ip_vs_in/ip_vs_out) + - 12 or more - packet traversal Only available when IPVS is compiled with CONFIG_IP_VS_DEBUG enabled. @@ -92,58 +99,58 @@ debug_level - INTEGER the level. drop_entry - INTEGER - 0 - disabled (default) + - 0 - disabled (default) - The drop_entry defense is to randomly drop entries in the - connection hash table, just in order to collect back some - memory for new connections. In the current code, the - drop_entry procedure can be activated every second, then it - randomly scans 1/32 of the whole and drops entries that are in - the SYN-RECV/SYNACK state, which should be effective against - syn-flooding attack. + The drop_entry defense is to randomly drop entries in the + connection hash table, just in order to collect back some + memory for new connections. In the current code, the + drop_entry procedure can be activated every second, then it + randomly scans 1/32 of the whole and drops entries that are in + the SYN-RECV/SYNACK state, which should be effective against + syn-flooding attack. - The valid values of drop_entry are from 0 to 3, where 0 means - that this strategy is always disabled, 1 and 2 mean automatic - modes (when there is no enough available memory, the strategy - is enabled and the variable is automatically set to 2, - otherwise the strategy is disabled and the variable is set to - 1), and 3 means that that the strategy is always enabled. + The valid values of drop_entry are from 0 to 3, where 0 means + that this strategy is always disabled, 1 and 2 mean automatic + modes (when there is no enough available memory, the strategy + is enabled and the variable is automatically set to 2, + otherwise the strategy is disabled and the variable is set to + 1), and 3 means that that the strategy is always enabled. drop_packet - INTEGER - 0 - disabled (default) + - 0 - disabled (default) - The drop_packet defense is designed to drop 1/rate packets - before forwarding them to real servers. If the rate is 1, then - drop all the incoming packets. + The drop_packet defense is designed to drop 1/rate packets + before forwarding them to real servers. If the rate is 1, then + drop all the incoming packets. - The value definition is the same as that of the drop_entry. In - the automatic mode, the rate is determined by the follow - formula: rate = amemthresh / (amemthresh - available_memory) - when available memory is less than the available memory - threshold. When the mode 3 is set, the always mode drop rate - is controlled by the /proc/sys/net/ipv4/vs/am_droprate. + The value definition is the same as that of the drop_entry. In + the automatic mode, the rate is determined by the follow + formula: rate = amemthresh / (amemthresh - available_memory) + when available memory is less than the available memory + threshold. When the mode 3 is set, the always mode drop rate + is controlled by the /proc/sys/net/ipv4/vs/am_droprate. expire_nodest_conn - BOOLEAN - 0 - disabled (default) - not 0 - enabled + - 0 - disabled (default) + - not 0 - enabled - The default value is 0, the load balancer will silently drop - packets when its destination server is not available. It may - be useful, when user-space monitoring program deletes the - destination server (because of server overload or wrong - detection) and add back the server later, and the connections - to the server can continue. + The default value is 0, the load balancer will silently drop + packets when its destination server is not available. It may + be useful, when user-space monitoring program deletes the + destination server (because of server overload or wrong + detection) and add back the server later, and the connections + to the server can continue. - If this feature is enabled, the load balancer will expire the - connection immediately when a packet arrives and its - destination server is not available, then the client program - will be notified that the connection is closed. This is - equivalent to the feature some people requires to flush - connections when its destination is not available. + If this feature is enabled, the load balancer will expire the + connection immediately when a packet arrives and its + destination server is not available, then the client program + will be notified that the connection is closed. This is + equivalent to the feature some people requires to flush + connections when its destination is not available. expire_quiescent_template - BOOLEAN - 0 - disabled (default) - not 0 - enabled + - 0 - disabled (default) + - not 0 - enabled When set to a non-zero value, the load balancer will expire persistent templates when the destination server is quiescent. @@ -158,8 +165,8 @@ expire_quiescent_template - BOOLEAN connection and the destination server is quiescent. ignore_tunneled - BOOLEAN - 0 - disabled (default) - not 0 - enabled + - 0 - disabled (default) + - not 0 - enabled If set, ipvs will set the ipvs_property on all packets which are of unrecognized protocols. This prevents us from routing tunneled @@ -168,30 +175,30 @@ ignore_tunneled - BOOLEAN ipvs routing loops when ipvs is also acting as a real server). nat_icmp_send - BOOLEAN - 0 - disabled (default) - not 0 - enabled + - 0 - disabled (default) + - not 0 - enabled - It controls sending icmp error messages (ICMP_DEST_UNREACH) - for VS/NAT when the load balancer receives packets from real - servers but the connection entries don't exist. + It controls sending icmp error messages (ICMP_DEST_UNREACH) + for VS/NAT when the load balancer receives packets from real + servers but the connection entries don't exist. pmtu_disc - BOOLEAN - 0 - disabled - not 0 - enabled (default) + - 0 - disabled + - not 0 - enabled (default) By default, reject with FRAG_NEEDED all DF packets that exceed the PMTU, irrespective of the forwarding method. For TUN method the flag can be disabled to fragment such packets. secure_tcp - INTEGER - 0 - disabled (default) + - 0 - disabled (default) The secure_tcp defense is to use a more complicated TCP state transition table. For VS/NAT, it also delays entering the TCP ESTABLISHED state until the three way handshake is completed. - The value definition is the same as that of drop_entry and - drop_packet. + The value definition is the same as that of drop_entry and + drop_packet. sync_threshold - vector of 2 INTEGERs: sync_threshold, sync_period default 3 50 @@ -248,8 +255,8 @@ sync_ports - INTEGER 8848+sync_ports-1. snat_reroute - BOOLEAN - 0 - disabled - not 0 - enabled (default) + - 0 - disabled + - not 0 - enabled (default) If enabled, recalculate the route of SNATed packets from realservers so that they are routed as if they originate from the @@ -270,6 +277,7 @@ sync_persist_mode - INTEGER Controls the synchronisation of connections when using persistence 0: All types of connections are synchronised + 1: Attempt to reduce the synchronisation traffic depending on the connection type. For persistent services avoid synchronisation for normal connections, do it only for persistence templates. diff --git a/MAINTAINERS b/MAINTAINERS index 3764697a6002..2828723f0d4d 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -8957,7 +8957,7 @@ L: lvs-devel@vger.kernel.org S: Maintained T: git git://git.kernel.org/pub/scm/linux/kernel/git/horms/ipvs-next.git T: git git://git.kernel.org/pub/scm/linux/kernel/git/horms/ipvs.git -F: Documentation/networking/ipvs-sysctl.txt +F: Documentation/networking/ipvs-sysctl.rst F: include/net/ip_vs.h F: include/uapi/linux/ip_vs.h F: net/netfilter/ipvs/