From patchwork Wed Jul 26 14:39:49 2017 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Olaf Hering X-Patchwork-Id: 9865189 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 119AD6038C for ; Wed, 26 Jul 2017 14:42:33 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 0774F2871C for ; Wed, 26 Jul 2017 14:42:33 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id F053928733; Wed, 26 Jul 2017 14:42:32 +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 EFD3628740 for ; Wed, 26 Jul 2017 14:42:31 +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 1daNTr-00051l-5S; Wed, 26 Jul 2017 14:40:07 +0000 Received: from mail6.bemta6.messagelabs.com ([193.109.254.103]) by lists.xenproject.org with esmtp (Exim 4.84_2) (envelope-from ) id 1daNTq-00051T-GQ for xen-devel@lists.xen.org; Wed, 26 Jul 2017 14:40:06 +0000 Received: from [85.158.143.35] by server-8.bemta-6.messagelabs.com id 1C/6A-09901-5C9A8795; Wed, 26 Jul 2017 14:40:05 +0000 X-Brightmail-Tracker: H4sIAAAAAAAAA+NgFvrFLMWRWlGSWpSXmKPExsUSuHLSXd0jKys iDRZMNrNY8nExiwOjx9Hdv5kCGKNYM/OS8isSWDP2LbjOUvDfq+LvzueMDYznbLsYuThYBH4x SXy4tYu9i5GTQ0IgV2JO71zWLkYOIFtE4sn/NJAaIYFDTBJTOhewgtSwCShJ7D14nBHEFhFIl ZgxtZsFxGYWUJB48XwrE4gtLOAtsX/fdLAaFgFVic4rX8BqeAWMJTY3NTFC7JKXeNf/FKyeU8 BEYtLu92A3CAHVrLz2jGUCI+8CRoZVjBrFqUVlqUW6RpZ6SUWZ6RkluYmZObqGBmZ6uanFxYn pqTmJScV6yfm5mxiB4cAABDsYDywKPMQoycGkJMo7ybQiUogvKT+lMiOxOCO+qDQntfgQowwH h5IEb80KoJxgUWp6akVaZg4wMGHSEhw8SiK8jSBp3uKCxNzizHSI1ClGXY5XE/5/YxJiycvPS 5US560DKRIAKcoozYMbAYuSS4yyUsK8jEBHCfEUpBblZpagyr9iFOdgVBLmXQgyhSczrwRu0y ugI5iAjpgzoxTkiJJEhJRUA6Pbhcu7ytbNmXZ9hWJjpO5j7kK2rre+ZeGqzLELziVOOi7w8vf cwizO9S17umO+GUXXPdV6te2We8PxObmOa7eGarjNeJjAM//a2dyuM6IemzjijUw9vzE4bp1f mbsmTIZ3VdFyIy3Glt+X3z/Km5tsE9Ma0HLt5xGto5eDZs2RZjf79Tvdn0WJpTgj0VCLuag4E QCP3i7/jQIAAA== X-Env-Sender: olaf@aepfle.de X-Msg-Ref: server-10.tower-21.messagelabs.com!1501080004!68410199!1 X-Originating-IP: [81.169.146.221] 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 29974 invoked from network); 26 Jul 2017 14:40:04 -0000 Received: from mo4-p00-ob.smtp.rzone.de (HELO mo4-p00-ob.smtp.rzone.de) (81.169.146.221) by server-10.tower-21.messagelabs.com with DHE-RSA-AES256-GCM-SHA384 encrypted SMTP; 26 Jul 2017 14:40:04 -0000 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; t=1501080004; l=9774; s=domk; d=aepfle.de; h=References:In-Reply-To:Date:Subject:Cc:To:From; bh=qOQ7f90KMM5UPqZNztzwOugh/8EKjWM/6Th5z6+2v2o=; b=ofdHP6Arc4qmeXCCVdCqx4AMcfwokR9N40Y8+Ogzyo41ANeaETt4H/9miKNHsaE5n3 ZP6KoyJbEeJGtPDHFY+RBX3D/3shONwVVrmShOsOs81ORtFdVgdKeID+GFPlokQMhYHI vRsCznuVkyoSfVRD9z4whEyfQHKqFKx7Y7IjM= X-RZG-AUTH: :P2EQZWCpfu+qG7CngxMFH1J+yackYocTD1iAi8x+OWi/zfN1cLnAYQz4nTxeMfYqQUynrTNSUxxRmo+kS0vrvFOiwqvPcA== X-RZG-CLASS-ID: mo00 Received: from sender ([2001:a61:3458:10ff:1629:d398:f8f9:5e72]) by smtp.strato.de (RZmta 41.1 AUTH) with ESMTPSA id v056act6QEe1CuB (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); Wed, 26 Jul 2017 16:40:01 +0200 (CEST) From: Olaf Hering To: xen-devel@lists.xen.org, Ian Jackson , Wei Liu Date: Wed, 26 Jul 2017 16:39:49 +0200 Message-Id: <20170726143950.30329-3-olaf@aepfle.de> X-Mailer: git-send-email 2.13.2 In-Reply-To: <20170726143950.30329-1-olaf@aepfle.de> References: <20170726143950.30329-1-olaf@aepfle.de> Cc: Olaf Hering Subject: [Xen-devel] [PATCH v3 2/3] 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 Convert source for xl-network-configuration.5 from markdown to pod. 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 --- ...n.markdown.5 => xl-network-configuration.pod.5} | 196 ++++++++++++++------- 1 file changed, 137 insertions(+), 59 deletions(-) rename docs/man/{xl-network-configuration.markdown.5 => xl-network-configuration.pod.5} (55%) diff --git a/docs/man/xl-network-configuration.markdown.5 b/docs/man/xl-network-configuration.pod.5 similarity index 55% rename from docs/man/xl-network-configuration.markdown.5 rename to docs/man/xl-network-configuration.pod.5 index 84c2645ad8..e9ac3c5b9e 100644 --- a/docs/man/xl-network-configuration.markdown.5 +++ b/docs/man/xl-network-configuration.pod.5 @@ -1,6 +1,11 @@ -# XL Network Configuration +=encoding utf8 -## Syntax Overview +=head1 NAME + +xl-network-configuration - XL Network Configuration Syntax + + +=head1 SYNTAX This document specifies the xl config file format vif configuration option. It has the following form: @@ -8,7 +13,7 @@ option. It has the following form: vif = [ '', '', ... ] where each vifspec is in this form: - + [=|,] For example: @@ -24,11 +29,13 @@ These might be specified in the domain config file like this: More formally, the string is a series of comma-separated keyword/value pairs. All keywords are optional. -Each device has a `DEVID` which is its index within the vif list, starting from 0. +Each device has a C which is its index within the vif list, starting from 0. -## Keywords -### mac +=head1 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 @@ -36,89 +43,137 @@ 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 -[Organizationally Unique Identifier][oui] (00:16:3e). +L (00:16:3e). If you are choosing a MAC address then it is strongly recommend to follow one of the following strategies: - * 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. - * 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. - * 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. +=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. -### bridge + +=head2 bridge Specifies the name of the network bridge which this VIF should be -added to. The default is `xenbr0`. The bridge must be configured using -your distribution's network configuration tools. See the [wiki][net] +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. -### gatewaydev + +=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 [wiki][vifroute] for guidance and +by the vif-route hotplug script. See L for guidance and examples. NOTE: netdev is a deprecated alias of this option. -### type + +=head2 type This keyword is valid for HVM guests only. Specifies the type of device to valid values are: - * `ioemu` (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. - * `vif` -- this device will be provided as a paravirtualised device - only. +=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 * -### model +C -- this device will be provided as a paravirtualised device +only. -This keyword is valid for HVM guest devices with `type=ioemu` 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: - * `rtl8139` (default) -- Realtek RTL8139 - * `e1000` -- Intel E1000 - * in principle any device supported by your device model +=over + +=item * + +C (default) -- Realtek RTL8139 + -### vifname +=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 `vifDOMID.DEVID` where -`DOMID` is the guest domain ID and `DEVID` is the device -number. Likewise the default tap name is `vifDOMID.DEVID-emu`. +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. -### script + +=head2 script Specifies the hotplug script to run to configure this device (e.g. to add it to the relevant bridge). Defaults to -`XEN_SCRIPT_DIR/vif-bridge` but can be set to any script. Some example -scripts are installed in `XEN_SCRIPT_DIR`. +C but can be set to any script. Some example +scripts are installed in C. + -### ip +=head2 ip Specifies the IP address for the device, the default is not to specify an IP address. @@ -128,25 +183,51 @@ 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). -### backend + +=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. -### rate + +=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@". +The rate may be specified as "/s" or optionally "/s@". + +=over + +=item * + +C is in bytes and can accept suffixes: - * `RATE` is in bytes and can accept suffixes: - * GB, MB, KB, B for bytes. - * Gb, Mb, Kb, b for bits. - * `INTERVAL` 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. +=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 @@ -162,12 +243,9 @@ For example: NOTE: The actual underlying limits of rate limiting are dependent on the underlying netback implementation. -### devid + +=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. - -[oui]: http://en.wikipedia.org/wiki/Organizationally_Unique_Identifier -[net]: http://wiki.xen.org/wiki/HostConfiguration/Networking -[vifroute]: http://wiki.xen.org/wiki/Vif-route