diff --git a/doc/source/acknowledgements.rst b/doc/source/acknowledgements.rst index ad027b78..925de5ae 100644 --- a/doc/source/acknowledgements.rst +++ b/doc/source/acknowledgements.rst @@ -45,7 +45,7 @@ facilitator Adam Hyde. Without his tireless support and encouragement, we would have thought a book of this scope was impossible in five days. Adam has proven the book sprint method effectively again and again. He creates both tools and faith in collaborative authoring at -`www.booksprints.net `_. +`www.booksprints.net `_. We couldn't have pulled it off without so much supportive help and encouragement. diff --git a/doc/source/app-crypt.rst b/doc/source/app-crypt.rst index 35480419..88d8da8d 100644 --- a/doc/source/app-crypt.rst +++ b/doc/source/app-crypt.rst @@ -213,10 +213,10 @@ its lease and all of the sudden I found a bunch of OpenStack and dnsmasq discussions that were identical to the problem we were seeing! `Problem with Heavy Network IO and -Dnsmasq `_. +Dnsmasq `_. `instances losing IP address while running, due to No -DHCPOFFER `_. +DHCPOFFER `_. Seriously, Google. @@ -245,7 +245,7 @@ Disappearing Images At the end of 2012, Cybera (a nonprofit with a mandate to oversee the development of cyberinfrastructure in Alberta, Canada) deployed an updated OpenStack cloud for their `DAIR -project `_. A few days into +project `_. A few days into production, a compute node locks up. Upon rebooting the node, I checked to see what instances were hosted on that node so I could boot them on behalf of the customer. Luckily, only one instance. diff --git a/doc/source/app-resources.rst b/doc/source/app-resources.rst index 1c998987..e1bd0678 100644 --- a/doc/source/app-resources.rst +++ b/doc/source/app-resources.rst @@ -16,14 +16,13 @@ OpenStack - `OpenStack Administrator Guide `_ -- `OpenStack Cloud Computing Cookbook (Packt - Publishing) `_ +- `OpenStack Cloud Computing Cookbook `_ Cloud (General) ~~~~~~~~~~~~~~~ - `The NIST Definition of Cloud - Computing `_ + Computing `_ Python ~~~~~~ @@ -34,29 +33,29 @@ Networking ~~~~~~~~~~ - `TCP/IP Illustrated, Volume 1: The Protocols, 2/E - (Pearson) `_ + (Pearson) `_ - `The TCP/IP Guide (No Starch - Press) `_ + Press) `_ - `A tcpdump Tutorial and - Primer `_ + Primer `_ Systems Administration ~~~~~~~~~~~~~~~~~~~~~~ - `UNIX and Linux Systems Administration Handbook (Prentice - Hall) `_ + Hall) `_ Virtualization ~~~~~~~~~~~~~~ - `The Book of Xen (No Starch - Press) `_ + Press) `_ Configuration Management ~~~~~~~~~~~~~~~~~~~~~~~~ -- `Puppet Labs Documentation `_ +- `Puppet Labs Documentation `_ -- `Pro Puppet (Apress) `_ +- `Pro Puppet (Apress) `_ diff --git a/doc/source/app-usecases.rst b/doc/source/app-usecases.rst index 595a8ea9..bc7b5078 100644 --- a/doc/source/app-usecases.rst +++ b/doc/source/app-usecases.rst @@ -40,13 +40,8 @@ to 10 percent back-ported code from trunk and modifications. Resources --------- -- `OpenStack.org case - study `_ - - `NeCTAR-RC GitHub `_ -- `NeCTAR website `_ - MIT CSAIL ~~~~~~~~~ @@ -110,7 +105,7 @@ based networks. Resources --------- -- `CSAIL homepage `_ +- `CSAIL homepage `_ DAIR ~~~~ @@ -151,7 +146,7 @@ controller. Resources --------- -- `DAIR homepage `__ +- `DAIR homepage `__ CERN ~~~~ @@ -183,7 +178,7 @@ Resources --------- - `OpenStack in Production: A tale of 3 OpenStack - Clouds `_ + Clouds `_ - `Review of CERN Data Centre Infrastructure `_ diff --git a/doc/source/common/app-support.rst b/doc/source/common/app-support.rst index 3c8f960a..ea264756 100644 --- a/doc/source/common/app-support.rst +++ b/doc/source/common/app-support.rst @@ -182,8 +182,8 @@ Documentation feedback To provide feedback on documentation, join our IRC channel ``#openstack-doc`` on the Freenode IRC network, or `report a bug in Launchpad -`_ and choose the particular -project that the documentation is a part of. +`_ and choose +the particular project that the documentation is a part of. The OpenStack IRC channel ~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -194,7 +194,7 @@ feedback for urgent and pressing issues. To install an IRC client or use a browser-based client, go to `https://webchat.freenode.net/ `_. You can also use `Colloquy `_ (Mac OS X), -`mIRC `_ (Windows), +`mIRC `_ (Windows), or XChat (Linux). When you are in the IRC channel and want to share code or command output, the generally accepted method is to use a Paste Bin. The OpenStack project has one at `Paste diff --git a/doc/source/index.rst b/doc/source/index.rst index dd5b3dba..bf6622f9 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -8,14 +8,14 @@ Abstract This guide provides information about operating OpenStack clouds. We recommend that you turn to the `Installation Tutorials and Guides -`_, +`_, which contains a step-by-step guide on how to manually install the OpenStack packages and dependencies on your cloud. While it is important for an operator to be familiar with the steps involved in deploying OpenStack, we also strongly encourage you to evaluate `OpenStack deployment tools -`_ +`_ and configuration-management tools, such as :term:`Puppet` or :term:`Chef`, which can help automate this deployment process. diff --git a/doc/source/ops-advanced-configuration.rst b/doc/source/ops-advanced-configuration.rst index 502749b2..a7c0ab29 100644 --- a/doc/source/ops-advanced-configuration.rst +++ b/doc/source/ops-advanced-configuration.rst @@ -34,7 +34,7 @@ different tuning requirements. `__. You can see a matrix of the various features in OpenStack Compute (nova) hypervisor drivers at the `Hypervisor support matrix - page `_. + page `_. The point we are trying to make here is that just because an option exists doesn't mean that option is relevant to your driver choices. @@ -146,6 +146,6 @@ quickly based on the closest data center. You configure a default region with one zone for each cluster, but be sure your network (WAN) can handle the additional request and response load between zones as you add more zones and build a ring that handles more zones. Refer to -`Geographically Distributed Clusters -`_ +`Geographically Distributed Swift Considerations +`_ in the documentation for additional information. diff --git a/doc/source/ops-capacity-planning-scaling.rst b/doc/source/ops-capacity-planning-scaling.rst index dd6d6b2d..07c91f0f 100644 --- a/doc/source/ops-capacity-planning-scaling.rst +++ b/doc/source/ops-capacity-planning-scaling.rst @@ -150,7 +150,7 @@ load-balancing method (DNS round robin, hardware load balancer, or software such as Pound or HAProxy). One caveat with dashboard is the VNC proxy, which uses the WebSocket protocol— something that an L7 load balancer might struggle with. See also `Horizon session storage -`_. +`_. You can configure some services, such as ``nova-api`` and ``glance-api``, to use multiple processes by changing a flag in their diff --git a/doc/source/ops-customize-dashboard.rst b/doc/source/ops-customize-dashboard.rst index 097edcc0..3f034e6e 100644 --- a/doc/source/ops-customize-dashboard.rst +++ b/doc/source/ops-customize-dashboard.rst @@ -5,4 +5,4 @@ Customizing the Dashboard (Horizon) The dashboard is based on the Python `Django `_ web application framework. To know how to build your Dashboard, see `Building a Dashboard using Horizon -`_. +`_. diff --git a/doc/source/ops-customize-development.rst b/doc/source/ops-customize-development.rst index a5ec4c85..dc7c9386 100644 --- a/doc/source/ops-customize-development.rst +++ b/doc/source/ops-customize-development.rst @@ -8,4 +8,4 @@ builds an OpenStack development environment for you. You use it to create such an environment for developing a new feature. For more information on installing DevStack, see the -`DevStack `_ website. +`DevStack `_ website. diff --git a/doc/source/ops-customize-objectstorage.rst b/doc/source/ops-customize-objectstorage.rst index 0388aada..3788fa09 100644 --- a/doc/source/ops-customize-objectstorage.rst +++ b/doc/source/ops-customize-objectstorage.rst @@ -3,9 +3,9 @@ Customizing Object Storage (Swift) Middleware ============================================= OpenStack Object Storage, known as swift when reading the code, is based -on the Python `Paste `_ framework. The best -introduction to its architecture is `A Do-It-Yourself -Framework `_. +on the Python `Paste `_ framework. +The best introduction to its architecture is on `Read The +Docs `_. Because of the swift project's use of this framework, you are able to add features to a project by placing some custom code in a project's pipeline without having to change any of the core code. diff --git a/doc/source/ops-deployment-factors.rst b/doc/source/ops-deployment-factors.rst index c4229cac..d255f1db 100644 --- a/doc/source/ops-deployment-factors.rst +++ b/doc/source/ops-deployment-factors.rst @@ -217,9 +217,9 @@ Common areas of regulation include: This is an example of such legal frameworks: Data storage regulations in Europe are currently driven by provisions of -the `Data protection framework `_. +the `Data protection board `_. `Financial Industry Regulatory Authority -`_ works on this in +`_ works on this in the United States. Privacy and security are spread over different industry-specific laws and @@ -262,7 +262,7 @@ Corrective controls: system is an example of a corrective control. For more information, see See also `NIST Special Publication 800-53 -`_. +`_. Software licensing diff --git a/doc/source/ops-lay-of-the-land.rst b/doc/source/ops-lay-of-the-land.rst index 75921cd7..c53a7032 100644 --- a/doc/source/ops-lay-of-the-land.rst +++ b/doc/source/ops-lay-of-the-land.rst @@ -18,7 +18,7 @@ tab with a :guilabel:`System Panel` and an :guilabel:`Identity` tab. These interfaces give you access to system information and usage as well as to settings for configuring what end users can do. Refer to the `OpenStack Administrator -Guide `__ for +Guide `__ for detailed how-to information about using the dashboard as an admin user. Command-Line Tools @@ -40,9 +40,8 @@ Install OpenStack command-line clients -------------------------------------- For instructions on installing, upgrading, or removing command-line clients, -see the `Install the OpenStack command-line clients -`_ -section in OpenStack End User Guide. +see the `Install the OpenStack command-line client +`_. .. note:: @@ -209,7 +208,7 @@ Underlying the use of the command-line tools is the OpenStack API, which is a RESTful API that runs over HTTP. There may be cases where you want to interact with the API directly or need to use it because of a suspected bug in one of the CLI tools. The best way to do this is to use -a combination of `cURL `_ and another tool, +a combination of `cURL `_ and another tool, such as `jq `_, to parse the JSON from the responses. @@ -589,5 +588,5 @@ Summary We hope you have enjoyed this quick tour of your working environment, including how to interact with your cloud and extract useful information. From here, you can use the `OpenStack Administrator -Guide `_ as your +Guide `_ as your reference for all of the command-line functionality in your cloud. diff --git a/doc/source/ops-maintenance-configuration.rst b/doc/source/ops-maintenance-configuration.rst index 16c3c77d..6b589512 100644 --- a/doc/source/ops-maintenance-configuration.rst +++ b/doc/source/ops-maintenance-configuration.rst @@ -16,14 +16,14 @@ configuration options) in a version-controlled repository. not recommend a specific one. The most popular ones in the OpenStack community are: - * `Puppet `_, with available `OpenStack + * `Puppet `_, with available `OpenStack Puppet modules `_ * `Ansible `_, with `OpenStack Ansible `_ - * `Chef `_, with available `OpenStack Chef + * `Chef `_, with available `OpenStack Chef recipes `_ - Other newer configuration tools include `Juju `_ + Other newer configuration tools include `Juju `_ and `Salt `_; and more mature configuration - management tools include `CFEngine `_ and `Bcfg2 + management tools include `CFEngine `_ and `Bcfg2 `_. diff --git a/doc/source/ops-maintenance-database.rst b/doc/source/ops-maintenance-database.rst index 798ec63c..b3d592b2 100644 --- a/doc/source/ops-maintenance-database.rst +++ b/doc/source/ops-maintenance-database.rst @@ -48,4 +48,4 @@ As your cloud grows, MySQL is utilized more and more. If you suspect that MySQL might be becoming a bottleneck, you should start researching MySQL optimization. The MySQL manual has an entire section dedicated to this topic: `Optimization Overview -`_. +`_. diff --git a/doc/source/ops-monitoring.rst b/doc/source/ops-monitoring.rst index e728698d..d9027d93 100644 --- a/doc/source/ops-monitoring.rst +++ b/doc/source/ops-monitoring.rst @@ -90,13 +90,11 @@ The Telemetry service (:term:`ceilometer`) collects metering and event data relating to OpenStack services. Data collected by the Telemetry service could be used for billing. Depending on deployment configuration, collected data may be accessible to users -based on the deployment configuration. The Telemetry service provides a -REST API documented at `ceilometer V2 Web API -`_. You can -read more about the module in the `OpenStack Administrator -Guide `_ or -in the `developer -documentation `_. +based on the deployment configuration. You can +read more about the module in the `Ceilometer Administrator +Guide `_ or +in the `Ceilometer Contributor +Guide `_. OpenStack Specific Resources ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/doc/source/ops-network-troubleshooting.rst b/doc/source/ops-network-troubleshooting.rst index 2cdf29ce..a19324f6 100644 --- a/doc/source/ops-network-troubleshooting.rst +++ b/doc/source/ops-network-troubleshooting.rst @@ -98,7 +98,7 @@ software defined networking (SDN) hardware or plug-ins that use Linux native facilities on your hosts, such as Open vSwitch or Linux Bridge. The networking chapter of the `OpenStack Administrator -Guide `_ +Guide `_ shows a variety of networking scenarios and their connection paths. The purpose of this section is to give you the tools to troubleshoot the various components involved however they are plumbed together in your @@ -473,7 +473,7 @@ is to use ``tcpdump``. We recommended using ``tcpdump`` at several points along the network path to correlate where a problem might be. If you prefer working with a GUI, either live or by using a ``tcpdump`` capture, check out -`Wireshark `_. +`Wireshark `_. For example, run the following command: @@ -920,7 +920,7 @@ Troubleshooting Open vSwitch Open vSwitch, as used in the previous OpenStack Networking examples is a full-featured multilayer virtual switch licensed under the open source Apache 2.0 license. Full documentation can be found at `the project's -website `_. In practice, given the preceding +website `_. In practice, given the preceding configuration, the most common issues are being sure that the required bridges (``br-int``, ``br-tun``, and ``br-ex``) exist and have the proper ports connected to them. @@ -1091,5 +1091,5 @@ analysis and diagnostic system that provides a completely automated service for verifying and diagnosing the networking functionality provided by OVS. Additionally, you can refer to -`neutron debug `_ +`neutron client `_ for more options. diff --git a/doc/source/ops-planning.rst b/doc/source/ops-planning.rst index 025682a7..ab9d923d 100644 --- a/doc/source/ops-planning.rst +++ b/doc/source/ops-planning.rst @@ -241,9 +241,9 @@ you build your use case and your deployment plan. For further research about OpenStack deployment, investigate the supported and documented preconfigured, prepackaged installers for OpenStack from companies such as - `Canonical `_, - `Cisco `_, - `Cloudscaling `_, + `Canonical `_, + `Cisco `_, + `Cloudscaling `_, `IBM `_, `Metacloud `_, `Mirantis `_, diff --git a/doc/source/ops-upgrades.rst b/doc/source/ops-upgrades.rst index 0fbb033c..b0362fb3 100644 --- a/doc/source/ops-upgrades.rst +++ b/doc/source/ops-upgrades.rst @@ -96,7 +96,7 @@ Watch the network To set up the test environment, you can use one of several methods: - Do a full manual install by using the `Installation Tutorials and Guides - `_ for + `_ for your platform. Review the final configuration files and installed packages. @@ -177,7 +177,7 @@ Upgrade process This section describes the process to upgrade a basic OpenStack deployment based on the basic two-node architecture in the `Installation Tutorials and Guides -`_. All +`_. All nodes must run a supported distribution of Linux with a recent kernel and the current release packages. @@ -188,23 +188,21 @@ Refer to the following upgrade notes for information on upgrading specific OpenStack services: * `Networking service (neutron) upgrades - `_ + `_ * `Compute service (nova) upgrades - `_ + `_ * `Identity service (keystone) upgrades - `_ + `_ * `Block Storage service (cinder) upgrades - `_ -* `Image service (glance) zero downtime database upgrades - `_ -* `Image service (glance) rolling upgrades - `_ + `_ +* `Image service (glance) database upgrades + `_ * `Bare Metal service (ironic) upgrades - `_ + `_ * `Object Storage service (swift) upgrades - `_ + `_ * `Telemetry service (ceilometer) upgrades - `_ + `_ Prerequisites ------------- @@ -253,7 +251,7 @@ Perform a backup Consider updating your SQL server configuration as described in the `Installation Tutorials and Guides - `_. + `_. Manage repositories ------------------- diff --git a/doc/source/ops-user-facing-operations.rst b/doc/source/ops-user-facing-operations.rst index d1e41baf..dba7cd4c 100644 --- a/doc/source/ops-user-facing-operations.rst +++ b/doc/source/ops-user-facing-operations.rst @@ -883,7 +883,7 @@ The default configuration of the Shared File Systems service depends on the back-end driver the admin chooses when starting the Shared File Systems service. For more information about existing back-end drivers, see `Share Backends -`__ +`__ of Shared File Systems service Developer Guide. For example, in case of OpenStack Block Storage based back-end is used, the Shared File Systems service cares about everything, including VMs, networking, keypairs, and @@ -907,37 +907,37 @@ large number of operations with shares: * Use security services For more information on share management see `Share management -`__ -of chapter “Shared File Systems” in OpenStack Administrator Guide. +`__ +in OpenStack Manila Administrator Guide. As to Security services, you should remember that different drivers support different authentication methods, while generic driver does not support Security Services at all (see section `Security services -`__ -of chapter “Shared File Systems” in OpenStack Administrator Guide). +`__ +in OpenStack Manila Administrator Guide). You can create a share in a network, list shares, and show information for, update, and delete a specified share. You can also create snapshots of shares (see `Share snapshots -`__ -of chapter “Shared File Systems” in OpenStack Administrator Guide). +`__ +in OpenStack Manila Administrator Guide). There are default and specific share types that allow you to filter or choose back-ends before you create a share. Functions and behaviour of share type is similar to Block Storage volume type (see `Share types -`__ -of chapter “Shared File Systems” in OpenStack Administrator Guide). +`__ +in OpenStack Manila Administrator Guide). To help users keep and restore their data, Shared File Systems service provides a mechanism to create and operate snapshots (see `Share snapshots -`__ -of chapter “Shared File Systems” in OpenStack Administrator Guide). +`__ +in OpenStack Manila Administrator Guide). A security service stores configuration information for clients for authentication and authorization. Inside Manila a share network can be associated with up to three security types (for detailed information see `Security services -`__ -of chapter “Shared File Systems” in OpenStack Administrator Guide): +`__ +in OpenStack Manila Administrator Guide). * LDAP * Kerberos @@ -958,16 +958,14 @@ called StandaloneNetworkPlugin is used. In this case, provide network information in the configuration: IP range, network type, and segmentation ID. Also you can add security services to a share network (see section -`“Networking” `__ -of chapter “Shared File Systems” in OpenStack Administrator Guide). +`“Networking” `__ +in OpenStack Manila Administrator Guide). The main idea of consistency groups is to enable you to create snapshots at the exact same point in time from multiple file system shares. Those snapshots can be then used for restoring all shares that were associated -with the consistency group (see section `“Consistency -groups” `__ -of chapter “Shared File Systems” in OpenStack Administrator Guide). +with the consistency group. Shared File System storage allows administrators to set limits and quotas for specific tenants and users. Limits are the resource @@ -1259,7 +1257,7 @@ specified access rules: For the details of features supported by different drivers see `Manila share features support mapping - `__ + `__ of Manila Developer Guide document. Manage Shares diff --git a/doc/source/preface.rst b/doc/source/preface.rst index 0c82c2e8..cf187ab4 100644 --- a/doc/source/preface.rst +++ b/doc/source/preface.rst @@ -284,7 +284,7 @@ We wrote this book to help you: We wrote this book in a book sprint, which is a facilitated, rapid development production method for books. For more information, see the -`BookSprints site `_. Your authors cobbled +`BookSprints site `_. Your authors cobbled this book together in five days during February 2013, fueled by caffeine and the best takeout food that Austin, Texas, could offer. @@ -332,7 +332,7 @@ Lorin Hochstein Adam Hyde Adam facilitated this book sprint. He also founded the book sprint methodology and is the most experienced book-sprint facilitator - around. See `BookSprints `_ for more + around. See `BookSprints `_ for more information. Adam founded FLOSS Manuals—a community of some 3,000 individuals developing Free Manuals about Free Software. He is also the founder and project manager for Booktype, an open source project for