From patchwork Mon Jul 24 14:14:46 2017 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Olaf Hering X-Patchwork-Id: 9859585 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork.web.codeaurora.org (Postfix) with ESMTP id 5A87E601A1 for ; Mon, 24 Jul 2017 14:17:44 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 4C0BF27FA3 for ; Mon, 24 Jul 2017 14:17:44 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 40F7D281B7; Mon, 24 Jul 2017 14:17:44 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-4.1 required=2.0 tests=BAYES_00,DKIM_SIGNED, RCVD_IN_DNSWL_MED,T_DKIM_INVALID autolearn=ham version=3.3.1 Received: from lists.xenproject.org (lists.xenproject.org [192.237.175.120]) (using TLSv1.2 with cipher AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by mail.wl.linuxfoundation.org (Postfix) with ESMTPS id A823C27FA3 for ; Mon, 24 Jul 2017 14:17:43 +0000 (UTC) Received: from localhost ([127.0.0.1] helo=lists.xenproject.org) by lists.xenproject.org with esmtp (Exim 4.84_2) (envelope-from ) id 1dZe8h-0004eo-Gi; Mon, 24 Jul 2017 14:15:15 +0000 Received: from mail6.bemta6.messagelabs.com ([193.109.254.103]) by lists.xenproject.org with esmtp (Exim 4.84_2) (envelope-from ) id 1dZe8g-0004dy-Pr for xen-devel@lists.xen.org; Mon, 24 Jul 2017 14:15:14 +0000 Received: from [193.109.254.147] by server-4.bemta-6.messagelabs.com id 28/8F-02962-2F006795; Mon, 24 Jul 2017 14:15:14 +0000 X-Brightmail-Tracker: H4sIAAAAAAAAA+NgFvrGLMWRWlGSWpSXmKPExsUSuHLSbd0PDGW RBh3n+C2WfFzM4sDocXT3b6YAxijWzLyk/IoE1oyfq+azFpwzr9h95TVzA2OPXhcjBweLwC8m iW3pXYycHBICuRLP5z5mAwlLCIhIPPmfBhIWEjjEJHF8UR2IzSagJLH34HFGEFtEIFVixtRuF hCbWUBB4sXzrUwgtrCAh8TLzbPAbBYBVYm1e06zg4zkFTCWmHyfFWKTvMS7/qdgJZwCJhJbn3 5mh1hlLNF49Q/TBEbeBYwMqxg1ilOLylKLdI0M9JKKMtMzSnITM3N0DQ3M9HJTi4sT01NzEpO K9ZLzczcxAsOAAQh2MP5aFnCIUZKDSUmUd/m6okghvqT8lMqMxOKM+KLSnNTiQ4wyHBxKErz2 /0sjhQSLUtNTK9Iyc4ABCZOW4OBREuHNBEnzFhck5hZnpkOkTjHqcrya8P8bkxBLXn5eqpQ47 2qQIgGQoozSPLgRsOi4xCgrJczLCHSUEE9BalFuZgmq/CtGcQ5GJWHe/yBTeDLzSuA2vQI6gg noiDkzwI4oSURISTUwxjo5Tkpi/rHpscDvBHcejezTM6zP3rh+4Ny2kL6TrjdX3jSOvCzY9u3 61xczH+5L/Dqbvyz+laali0vKI+6nHXI/9le+l3ePlOjedF9wYexcOY+HNUc47ziUPKhiPHnI 95zW9udGYVO2/RDyWnHg5I8DVi/uz7J02Xv4Vq5YeGBOXvtSkU1z9yqxFGckGmoxFxUnAgBZM JoViQIAAA== X-Env-Sender: olaf@aepfle.de X-Msg-Ref: server-13.tower-27.messagelabs.com!1500905711!99077839!1 X-Originating-IP: [81.169.146.219] X-SpamReason: No, hits=0.5 required=7.0 tests=BODY_RANDOM_LONG X-StarScan-Received: X-StarScan-Version: 9.4.25; banners=-,-,- X-VirusChecked: Checked Received: (qmail 43970 invoked from network); 24 Jul 2017 14:15:12 -0000 Received: from mo4-p00-ob.smtp.rzone.de (HELO mo4-p00-ob.smtp.rzone.de) (81.169.146.219) by server-13.tower-27.messagelabs.com with DHE-RSA-AES256-GCM-SHA384 encrypted SMTP; 24 Jul 2017 14:15:12 -0000 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; t=1500905711; l=7318; s=domk; d=aepfle.de; h=References:In-Reply-To:Date:Subject:Cc:To:From; bh=7UvlOFDcC2Bro9wQ6SGZ8cByXzbASpf+D043KmHeL/0=; b=PdAwwKV/NrOTWuX2qibFPxXiwbsbwwBYerodDJ8xqRn3v32VWOKAk3Lzpl9KNfIILI avyq7g8rF/OE43UObslW/kWvMTePBT8bnFoObVrwnUBRNZnYT0zGDFMTrzxMl+z82pqs Dr4pE1/g2HKq329g+VCGHIJ3+RIWW/IGfA9Mk= X-RZG-AUTH: :P2EQZWCpfu+qG7CngxMFH1J+yackYocTD1iAi8x+OWi/zfN1cLnAYQz4nWZeYaUqZmDcaKDKWuInYjY1AKYxM/KZ8U5sbA== X-RZG-CLASS-ID: mo00 Received: from sender ([2001:a61:345b:acff:1864:5839:ae0e:f6b6]) by smtp.strato.de (RZmta 41.1 AUTH) with ESMTPSA id 50583et6OEF9LKy (using TLSv1.2 with cipher ECDHE-RSA-AES256-SHA (curve secp521r1 with 521 ECDH bits, eq. 15360 bits RSA)) (Client did not present a certificate); Mon, 24 Jul 2017 16:15:09 +0200 (CEST) From: Olaf Hering To: xen-devel@lists.xen.org, Ian Jackson , Wei Liu Date: Mon, 24 Jul 2017 16:14:46 +0200 Message-Id: <20170724141450.22971-3-olaf@aepfle.de> X-Mailer: git-send-email 2.13.2 In-Reply-To: <20170724141450.22971-1-olaf@aepfle.de> References: <20170724141450.22971-1-olaf@aepfle.de> Cc: Olaf Hering Subject: [Xen-devel] [PATCH 2/6] docs: add pod variant of xl-network-configuration.5 X-BeenThere: xen-devel@lists.xen.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: Xen developer discussion List-Unsubscribe: , List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Errors-To: xen-devel-bounces@lists.xen.org Sender: "Xen-devel" X-Virus-Scanned: ClamAV using ClamSMTP Add source in pod format for xl-network-configuration.5 This removes the buildtime requirement for pandoc, and subsequently the need for ghc, in the chain for BuildRequires of xen.rpm. Signed-off-by: Olaf Hering --- docs/man/xl-network-configuration.pod.5 | 250 ++++++++++++++++++++++++++++++++ 1 file changed, 250 insertions(+) create mode 100644 docs/man/xl-network-configuration.pod.5 diff --git a/docs/man/xl-network-configuration.pod.5 b/docs/man/xl-network-configuration.pod.5 new file mode 100644 index 0000000000..9fa373e20d --- /dev/null +++ b/docs/man/xl-network-configuration.pod.5 @@ -0,0 +1,250 @@ +=encoding utf8 + + +=head1 XL Network Configuration + + +=head2 Syntax Overview + +This document specifies the xl config file format vif configuration +option. It has the following form: + + vif = [ '', '', ... ] + +where each vifspec is in this form: + + [=|,] + +For example: + + 'mac=00:16:3E:74:3d:76,model=rtl8139,bridge=xenbr0' + 'mac=00:16:3E:74:34:32' + '' # The empty string + +These might be specified in the domain config file like this: + + vif = [ 'mac=00:16:3E:74:34:32', 'mac=00:16:3e:5f:48:e4,bridge=xenbr1' ] + +More formally, the string is a series of comma-separated keyword/value +pairs. All keywords are optional. + +Each device has a C which is its index within the vif list, starting from 0. + + +=head2 Keywords + + +=head2 mac + +If specified then this option specifies the MAC address inside the +guest of this VIF device. The value is a 48-bit number represented as +six groups of two hexadecimal digits, separated by colons (:). + +The default if this keyword is not specified is to be automatically +generate a MAC address inside the space assigned to Xen's +L (00:16:3e). + +If you are choosing a MAC address then it is strongly recommend to +follow one of the following strategies: + +=over + +=item * + +Generate a random sequence of 6 byte, set the locally administered +bit (bit 2 of the first byte) and clear the multicast bit (bit 1 +of the first byte). In other words the first byte should have the +bit pattern xxxxxx10 (where x is a randomly generated bit) and the +remaining 5 bytes are randomly generated See +[http://en.wikipedia.org/wiki/MAC_address] for more details the +structure of a MAC address. + + +=item * + +Allocate an address from within the space defined by your +organization's OUI (if you have one) following your organization's +procedures for doing so. + + +=item * + +Allocate an address from within the space defined by Xen's OUI +(00:16:3e). Taking care not to clash with other users of the +physical network segment where this VIF will reside. + + +=back + +If you have an OUI for your own use then that is the preferred +strategy. Otherwise in general you should prefer to generate a random +MAC and set the locally administered bit since this allows for more +bits of randomness than using the Xen OUI. + + +=head2 bridge + +Specifies the name of the network bridge which this VIF should be +added to. The default is C. The bridge must be configured using +your distribution's network configuration tools. See the L +for guidance and examples. + + +=head2 gatewaydev + +Specifies the name of the network interface which has an IP and which +is in the network the VIF should communicate with. This is used in the host +by the vif-route hotplug script. See L for guidance and +examples. + +NOTE: netdev is a deprecated alias of this option. + + +=head2 type + +This keyword is valid for HVM guests only. + +Specifies the type of device to valid values are: + +=over + +=item * + +C (default) -- this device will be provided as an emulate +device to the guest and also as a paravirtualised device which the +guest may choose to use instead if it has suitable drivers +available. + + +=item * + +C -- this device will be provided as a paravirtualised device +only. + + +=back + + +=head2 model + +This keyword is valid for HVM guest devices with C only. + +Specifies the type device to emulated for this guest. Valid values +are: + +=over + +=item * + +C (default) -- Realtek RTL8139 + + +=item * + +C -- Intel E1000 + + +=item * + +in principle any device supported by your device model + + +=back + + +=head2 vifname + +Specifies the backend device name for the virtual device. + +If the domain is an HVM domain then the associated emulated (tap) +device will have a "-emu" suffice added. + +The default name for the virtual device is C where +C is the guest domain ID and C is the device +number. Likewise the default tap name is C. + + +=head2 script + +Specifies the hotplug script to run to configure this device (e.g. to +add it to the relevant bridge). Defaults to +C but can be set to any script. Some example +scripts are installed in C. + + +=head2 ip + +Specifies the IP address for the device, the default is not to +specify an IP address. + +What, if any, effect this has depends on the hotplug script which is +configured. A typically behaviour (exhibited by the example hotplug +scripts) if set might be to configure firewall rules to allow only the +specified IP address to be used by the guest (blocking all others). + + +=head2 backend + +Specifies the backend domain which this device should attach to. This +defaults to domain 0. Specifying another domain requires setting up a +driver domain which is outside the scope of this document. + + +=head2 rate + +Specifies the rate at which the outgoing traffic will be limited to. +The default if this keyword is not specified is unlimited. + +The rate may be specified as "/s" or optionally "/s@". + +=over + +=item * + +C is in bytes and can accept suffixes: + +=over + +=item * + +GB, MB, KB, B for bytes. + + +=item * + +Gb, Mb, Kb, b for bits. + + +=back + + + +=item * + +C is in microseconds and can accept suffixes: ms, us, s. +It determines the frequency at which the vif transmission credit +is replenished. The default is 50ms. + + +=back + +Vif rate limiting is credit-based. It means that for "1MB/s@20ms", the +available credit will be equivalent of the traffic you would have done +at "1MB/s" during 20ms. This will results in a credit of 20,000 bytes +replenished every 20,000 us. + +For example: + + 'rate=10Mb/s' -- meaning up to 10 megabits every second + 'rate=250KB/s' -- meaning up to 250 kilobytes every second + 'rate=1MB/s@20ms' -- meaning 20,000 bytes in every 20 millisecond period + +NOTE: The actual underlying limits of rate limiting are dependent +on the underlying netback implementation. + + +=head2 devid + +Specifies the devid manually instead of letting xl choose the lowest index available. + +NOTE: This should not be set unless you have a reason to.