operations-guide/doc/openstack-ops/preface_ops.xml

<?xml version="1.0" encoding="UTF-8"?>
<preface version="5.0" xml:id="openstack-ops_preface"
         xmlns="http://docbook.org/ns/docbook"
         xmlns:xlink="http://www.w3.org/1999/xlink"
         xmlns:xi="http://www.w3.org/2001/XInclude"
         xmlns:ns5="http://www.w3.org/1998/Math/MathML"
         xmlns:ns4="http://www.w3.org/2000/svg"
         xmlns:ns3="http://www.w3.org/1999/xhtml"
         xmlns:ns="http://docbook.org/ns/docbook">
  <?dbhtml stop-chunking?>

  <title>Preface</title>

  <para>OpenStack is an open source platform that lets you build an
  Infrastructure as a Service (IaaS) cloud that runs on commodity
  hardware.</para>

  <section xml:id="introduction-to-openstack">
    <title>Introduction to OpenStack</title>

    <para>OpenStack believes in open source, open design, open development,
    all in an open community that encourages participation by anyone. The
    long-term vision for OpenStack is to produce a ubiquitous open source
    cloud computing platform that meets the needs of public and private cloud
    providers regardless of size. OpenStack services control large pools of
    compute, storage, and networking resources throughout a data
    center.</para>

    <para>The technology behind OpenStack consists of a series of interrelated
    projects delivering various components for a cloud infrastructure
    solution. Each service provides an open API so that all of these resources
    can be managed through a dashboard that gives administrators control while
    empowering users to provision resources through a web interface, a
    command-line client, or software development kits that support the API.
    Many OpenStack APIs are extensible, meaning you can keep compatibility
    with a core set of calls while providing access to more resources and
    innovating through API extensions. The OpenStack project is a global
    collaboration of developers and cloud computing technologists. The project
    produces an open standard cloud computing platform for both public and
    private clouds. By focusing on ease of implementation, massive
    scalability, a variety of rich features, and tremendous extensibility, the
    project aims to deliver a practical and reliable cloud solution for all
    types of organizations.</para>
  </section>

  <section xml:id="preface_getting_started">
    <title>Getting Started with OpenStack</title>

    <para>As an open source project, one of the unique aspects of OpenStack is
    that it has many different levels at which you can begin to engage with
    it—you don't have to do everything yourself.</para>

    <section xml:id="preface_using_openstack">
      <title>Using OpenStack</title>

      <para>You could ask, "Do I even need to build a cloud?" If you want to
      start using a compute or storage service by just swiping your credit
      card, you can go to eNovance, HP, Rackspace, or other organizations to
      start using their public OpenStack clouds. Using their OpenStack cloud
      resources is similar to accessing the publically available Amazon Web
      Services Elastic Compute Cloud (EC2) or Simple Storage Solution
      (S3).</para>
    </section>

    <section xml:id="preface_plug_and_play">
      <title>Plug and Play OpenStack</title>

      <para>However, the enticing part of OpenStack might be to build your own
      private cloud, and there are several ways to accomplish this goal.
      Perhaps the simplest of all is an appliance-style solution. You purchase
      an appliance, unpack it, plug in the power and the network, and watch it
      transform into an OpenStack cloud with minimal additional configuration.
      Few, if any, other open source cloud products have such turnkey options.
      If a turnkey solution is interesting to you, take a look at Nebula
      One.</para>

      <para>However, hardware choice is important for many applications, so if
      that applies to you, consider that there are several software
      distributions available that you can run on servers, storage, and
      network products of your choosing. Canonical (where OpenStack replaced
      Eucalyptus as the default cloud option in 2011), Red Hat, and SUSE offer
      enterprise OpenStack solutions and support. You may also want to take a
      look at some of the specialized distributions, such as those from
      Rackspace, Piston, SwiftStack, or Cloudscaling. Also, a hat tip to
      Apache CloudStack, which Citrix donated to the Apache Foundation after
      its $200 million purchase of Cloud.com. While not currently packaged in
      any distributions, like Eucalyptus, it is an example of an alternative
      private cloud software developed in an open source–like manner.</para>

      <para>Alternatively, if you want someone to help guide you through the
      decisions about the underlying hardware or your applications, perhaps
      adding in a few features or integrating components along the way,
      consider contacting one of the system integrators with OpenStack
      experience, such as Mirantis or Metacloud.</para>

      <para>If your preference is to build your own OpenStack expertise
      internally, a good way to kick-start that might be to attend or arrange
      a training session. The OpenStack Foundation recently launched a <link
      xlink:href="http://opsgui.de/NPH6JZ">Training Marketplace</link> where
      you can look for nearby events. Also, the OpenStack community is <link
      xlink:href="http://opsgui.de/1eLCyio">working to produce</link> open
      source training materials.</para>
    </section>

    <section xml:id="preface_roll_your_own_openstack">
      <title>Roll Your Own OpenStack</title>

      <para>However, this guide has a different audience—those seeking to
      derive the most flexibility from the OpenStack framework by conducting
      do-it-yourself solutions.</para>

      <para>OpenStack is designed for scalability, so you can easily add new
      compute, network, and storage resources to grow your cloud over time. In
      addition to several massive OpenStack public clouds, a considerable
      number of organizations (such as Paypal, Intel, and Comcast) have built
      large-scale private clouds. OpenStack offers much more than a typical
      software package because it lets you integrate a number of different
      technologies to construct a cloud. This approach provides great
      flexibility, but the number of options might be bewildering at
      first.</para>
    </section>
  </section>

  <section xml:id="who-this-book-is-for">
    <title>Who This Book Is For</title>

    <para>This book is for those of you starting to run OpenStack clouds as
    well as those of you who were handed an operational one and want to keep
    it running well. Perhaps you're on a DevOps team, perhaps you are a system
    administrator starting to dabble in the cloud, or maybe you want to get on
    the OpenStack cloud team at your company. This book is for all of
    you.</para>

    <para>This guide assumes that you are familiar with a Linux distribution
      that supports OpenStack, SQL databases, and virtualization. You must be
      comfortable administering and configuring multiple Linux machines for
      networking. You must install and maintain an SQL database and occasionally
      run queries against it.</para>

    <para>One of the most complex aspects of an OpenStack cloud is the
    networking configuration. You should be familiar with concepts such as
    DHCP, Linux bridges, VLANs, and iptables. You must also have access to a
    network hardware expert who can configure the switches and routers
    required in your OpenStack cloud.</para>

    <tip>
      <para>Cloud computing is a quite advanced topic, and this book requires
      a lot of background knowledge. However, if you are fairly new to cloud
      computing, we recommend that you make use of the <xref
      linkend="openstack_glossary" /> at the back of the book, as well as the
      online documentation for OpenStack and additional resources mentioned in
      this book in <xref linkend="recommended-reading" />.</para>
    </tip>

    <section xml:id="further_reading">
      <title>Further Reading</title>

      <para>There are other books on the <link
      xlink:href="http://docs.openstack.org">OpenStack documentation
      website</link> that can help you get the job done.</para>

      <variablelist>
        <title>OpenStack Guides</title>

        <varlistentry>
          <term>OpenStack Installation Guides</term>

          <listitem>
            <para>Describes a manual installation process, as in, by hand,
            without automation, for multiple distributions based on a
            packaging system:</para>

            <itemizedlist>
              <listitem>
                <para><link xlink:href="http://opsgui.de/1eLBGtX">Installation
                Guide for Debian 7.0</link></para>
              </listitem>

              <listitem>
                <para><link xlink:href="http://opsgui.de/1eLBI50">Installation
                Guide for openSUSE and SUSE Linux Enterprise
                Server</link></para>
              </listitem>

              <listitem>
                <para><link xlink:href="http://opsgui.de/NPGvrs">Installation
                Guide for Red Hat Enterprise Linux, CentOS, and
                Fedora</link></para>
              </listitem>

              <listitem>
                <para><link xlink:href="http://opsgui.de/NPGunp">Installation
                Guide for Ubuntu 12.04 (LTS) Server</link></para>
              </listitem>
            </itemizedlist>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><link xlink:href="http://opsgui.de/1eLCDTf">OpenStack
          Configuration Reference</link></term>

          <listitem>
            <para>Contains a reference listing of all configuration options
            for core and integrated OpenStack services by release
            version</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><link xlink:href="http://opsgui.de/1eLBL0N">OpenStack Cloud
          Administrator Guide</link></term>

          <listitem>
            <para>Contains how-to information for managing an OpenStack cloud
            as needed for your use cases, such as storage, computing, or
            software-defined-networking</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><link xlink:href="http://opsgui.de/1eLCEGD">OpenStack High
          Availability Guide</link></term>

          <listitem>
            <para>Describes potential strategies for making your OpenStack
            services and related controllers and data stores highly
            available</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><link xlink:href="http://opsgui.de/NPG4NW">OpenStack Security
          Guide</link></term>

          <listitem>
            <para>Provides best practices and conceptual information about
            securing an OpenStack cloud</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><link xlink:href="http://opsgui.de/1eLCHlR">Virtual Machine
          Image Guide</link></term>

          <listitem>
            <para>Shows you how to obtain, create, and modify virtual machine
            images that are compatible with OpenStack</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><link xlink:href="http://opsgui.de/NPHaJI">OpenStack End User
          Guide</link></term>

          <listitem>
            <para>Shows OpenStack end users how to create and manage resources
            in an OpenStack cloud with the OpenStack dashboard and OpenStack
            client commands</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><link xlink:href="http://opsgui.de/1eLBkDJ">OpenStack Admin
          User Guide</link></term>

          <listitem>
            <para>Shows OpenStack administrators how to create and manage
            resources in an OpenStack cloud with the OpenStack dashboard and
            OpenStack client <phrase
            role="keep-together">commands</phrase></para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><link xlink:href="http://opsgui.de/NPHdVO">OpenStack API Quick
          Start</link></term>

          <listitem>
            <para>A brief overview of how to send REST API requests to
            endpoints for OpenStack services</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </section>
  </section>

  <section xml:id="how-this-book-is-organized">
    <title>How This Book Is Organized</title>

    <para>This book is organized in two parts: the architecture decisions for
    designing OpenStack clouds and the repeated operations for running
    OpenStack clouds.</para>

    <para><emphasis role="bold">Part I:</emphasis></para>

    <variablelist>
      <varlistentry>
        <term><xref linkend="example_architecture" /></term>

        <listitem>
          <para>Because of all the decisions the other chapters discuss, this
          chapter describes the decisions made for this particular book and
          much of the justification for the example architecture.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><xref linkend="section_arch_provision" /></term>

        <listitem>
          <para>While this book doesn't describe installation, we do recommend
          automation for deployment and configuration, discussed in this
          chapter.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><xref linkend="cloud_controller_design" /></term>

        <listitem>
          <para>The cloud controller is an invention for the sake of
          consolidating and describing which services run on which nodes. This
          chapter discusses hardware and network considerations as well as how
          to design the cloud controller for performance and separation of
          services.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><xref linkend="compute_nodes" /></term>

        <listitem>
          <para>This chapter describes the compute nodes, which are dedicated
          to running virtual machines. Some hardware choices come into play
          here, as well as logging and networking descriptions.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><xref linkend="scaling" /></term>

        <listitem>
          <para>This chapter discusses the growth of your cloud resources
          through scaling and segregation considerations.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><xref linkend="storage_decision" /></term>

        <listitem>
          <para>As with other architecture decisions, storage concepts within
          OpenStack take a lot of consideration, and this chapter lays out the
          choices for you.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><xref linkend="network_design" /></term>

        <listitem>
          <para>Your OpenStack cloud networking needs to fit into your
          existing networks while also enabling the best design for your users
          and administrators, and this chapter gives you in-depth information
          about networking decisions.</para>
        </listitem>
      </varlistentry>
    </variablelist>

    <para><emphasis role="bold">Part II:</emphasis></para>

    <variablelist>
      <varlistentry>
        <term><xref linkend="lay_of_the_land" /></term>

        <listitem>
          <para>This chapter is written to let you get your hands wrapped
          around your OpenStack cloud through command-line tools and
          understanding what is already set up in your cloud.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><xref linkend="projects_users" /></term>

        <listitem>
          <para>This chapter walks through user-enabling processes that all
          admins must face to manage users, give them quotas to parcel out
          resources, and so on.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><xref linkend="user_facing_operations" /></term>

        <listitem>
          <para>This chapter shows you how to use OpenStack cloud resources
          and train your users as well.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><xref linkend="maintenance" /></term>

        <listitem>
          <para>This chapter goes into the common failures that the authors
          have seen while running clouds in production, including
          troubleshooting.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><xref linkend="network_troubleshooting" /></term>

        <listitem>
          <para>Because network troubleshooting is especially difficult with
          virtual resources, this chapter is chock-full of helpful tips and
          tricks for tracing network traffic, finding the root cause of
          networking failures, and debugging related services, such as DHCP
          and DNS.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><xref linkend="logging_monitoring" /></term>

        <listitem>
          <para>This chapter shows you where OpenStack places logs and how to
          best read and manage logs for monitoring purposes.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><xref linkend="backup_and_recovery" /></term>

        <listitem>
          <para>This chapter describes what you need to back up within
          OpenStack as well as best practices for recovering backups.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><xref linkend="customize" /></term>

        <listitem>
          <para>For readers who need to get a specialized feature into
          OpenStack, this chapter describes how to use DevStack to write
          custom middleware or a custom scheduler to rebalance your
          resources.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><xref linkend="upstream_openstack" /></term>

        <listitem>
          <para>Because OpenStack is so, well, open, this chapter is dedicated
          to helping you navigate the community and find out where you can
          help and where you can get help.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><xref linkend="advanced_configuration" /></term>

        <listitem>
          <para>Much of OpenStack is driver-oriented, so you can plug in
          different solutions to the base set of services. This chapter
          describes some advanced configuration <phrase
          role="keep-together">topics</phrase>.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><xref linkend="ch_ops_upgrades" /></term>

        <listitem>
          <para>This chapter provides upgrade information based on the
          architectures used in this book.</para>
        </listitem>
      </varlistentry>
    </variablelist>

    <?hard-pagebreak ?>

    <para><emphasis role="bold">Backmatter:</emphasis></para>

    <variablelist>
      <varlistentry>
        <term><xref linkend="use-cases" /></term>

        <listitem>
          <para>You can read a small selection of use cases from the OpenStack
          community with some technical details and further resources.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><xref linkend="app_crypt" /></term>

        <listitem>
          <para>These are shared legendary tales of image disappearances, VM
          massacres, and crazy troubleshooting techniques to share those
          hard-learned lessons and <phrase
          role="keep-together">wisdom</phrase>.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><xref linkend="working-with-roadmaps" /></term>

        <listitem>
          <para>Read about how to track the OpenStack roadmap through the open
          and transparent development processes.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><xref linkend="recommended-reading" /></term>

        <listitem>
          <para>So many OpenStack resources are available online because of
          the fast-moving nature of the project, but there are also resources
          listed here that the authors found helpful while learning
          themselves.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><xref linkend="openstack_glossary" /></term>

        <listitem>
          <para>A list of terms used in this book is included, which is a
          subset of the larger OpenStack glossary available online.</para>
        </listitem>
      </varlistentry>
    </variablelist>
  </section>

  <section xml:id="why-and-how-we-wrote-this-book">
    <title>Why and How We Wrote This Book</title>

    <para>We wrote this book because we have deployed and maintained OpenStack
    clouds for at least a year, and wanted to be able to distribute this
    knowledge to others. After months of being the point people for an
    OpenStack cloud, we also wanted to have a document to hand to our system
    administrators so that they'd know how to operate the cloud on a daily
    basis—both reactively and proactively. We wanted to provide more detailed
    technical information about the decisions that deployers make along the
    way.</para>

    <para>We wrote this book to help you:<itemizedlist role="compact">
        <listitem>
          <para>Design and create an architecture for your first nontrivial
          OpenStack cloud. After you read this guide, you'll know which
          questions to ask and how to organize your compute, networking, and
          storage resources and the associated software packages.</para>
        </listitem>

        <listitem>
          <para>Perform the day-to-day tasks required to administer a
          cloud.</para>
        </listitem>
      </itemizedlist></para>

    <para>We wrote this book in a book sprint, which is a facilitated, rapid
    development production method for books. For more information, see the
    <link xlink:href="http://opsgui.de/1eLCIpY">BookSprints site</link>. Your
    authors cobbled this book together in five days during February 2013,
    fueled by caffeine and the best takeout food that Austin, Texas, could
    <phrase role="keep-together">offer</phrase>.</para>

    <para>On the first day, we filled white boards with colorful sticky notes
    to start to shape this nebulous book about how to architect and operate
    clouds:<informalfigure>
        <mediaobject>
          <imageobject>
            <imagedata fileref="figures/osog_00in01.png"></imagedata>
          </imageobject>
        </mediaobject>
      </informalfigure></para>

    <para>We wrote furiously from our own experiences and bounced ideas
    between each other. At regular intervals we reviewed the shape and
    organization of the book and further molded it, leading to what you see
    today.</para>

    <para>The team includes:</para>

    <variablelist>
      <varlistentry>
        <term>Tom Fifield</term>

        <listitem>
          <para>After learning about scalability in computing from particle
          physics experiments, such as ATLAS at the Large Hadron Collider
          (LHC) at CERN, Tom worked on OpenStack clouds in production to
          support the Australian public research sector. Tom currently serves
          as an OpenStack community manager and works on OpenStack
          documentation in his spare time.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Diane Fleming</term>

        <listitem>
          <para>Diane works on the OpenStack API documentation tirelessly. She
          helped out wherever she could on this project.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Anne Gentle</term>

        <listitem>
          <para>Anne is the documentation coordinator for OpenStack and also
          served as an individual contributor to the Google Documentation
          Summit in 2011, working with the Open Street Maps team. She has
          worked on book sprints in the past, with FLOSS Manuals’ Adam Hyde
          facilitating. Anne lives in Austin, Texas.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Lorin Hochstein</term>

        <listitem>
          <para>An academic turned software-developer-slash-operator, Lorin
          worked as the lead architect for Cloud Services at Nimbis Services,
          where he deploys OpenStack for technical computing applications. He
          has been working with OpenStack since the Cactus release.
          Previously, he worked on high-performance computing extensions for
          OpenStack at University of Southern California's Information
          Sciences Institute (USC-ISI).</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Adam Hyde</term>

        <listitem>
          <para>Adam facilitated this book sprint. He also founded the books
          sprint methodology and is the most experienced book-sprint
          facilitator around. See <link
          xlink:href="http://www.booksprints.net"></link> 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 writing, editing, and publishing books online and in
          print.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Jonathan Proulx</term>

        <listitem>
          <para>Jon has been piloting an OpenStack cloud as a senior technical
          architect at the MIT Computer Science and Artificial Intelligence
          Lab for his researchers to have as much computing power as they
          need. He started contributing to OpenStack documentation and
          reviewing the documentation so that he could accelerate his
          learning.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Everett Toews</term>

        <listitem>
          <para>Everett is a developer advocate at Rackspace making OpenStack
          and the Rackspace Cloud easy to use. Sometimes developer, sometimes
          advocate, and sometimes operator, he's built web applications,
          taught workshops, given presentations around the world, and deployed
          OpenStack for production use by academia and business.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Joe Topjian</term>

        <listitem>
          <para>Joe has designed and deployed several clouds at Cybera, a
          nonprofit where they are building e-infrastructure to support
          entrepreneurs and local researchers in Alberta, Canada. He also
          actively maintains and operates these clouds as a systems architect,
          and his experiences have generated a wealth of troubleshooting
          skills for cloud environments.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>OpenStack community members</term>

        <listitem>
          <para>Many individual efforts keep a community book alive. Our
          community members updated content for this book year-round. Also, a
          year after the first sprint, Jon Proulx hosted a second two-day
          mini-sprint at MIT with the goal of updating the book for the latest
          release. Since the book's inception, more than 30 contributors have
          supported this book. We have a tool chain for reviews, continuous
          builds, and translations. Writers and developers continuously review
          patches, enter doc bugs, edit content, and fix doc bugs. We want to
          recognize their efforts!</para>

          <para>The following people have contributed to this book: Akihiro
          Motoki, Alejandro Avella, Alexandra Settle, Andreas Jaeger, Andy
          McCallum, Benjamin Stassart, Chandan Kumar, Chris Ricker, David
          Cramer, David Wittman, Denny Zhang, Emilien Macchi, Gauvain
          Pocentek, Ignacio Barrio, James E. Blair, Jay Clark, Jeff White,
          Jeremy Stanley, K Jonathan Harker, KATO Tomoyuki, Lana Brindley,
          Laura Alves, Lee Li, Lukasz Jernas, Mario B. Codeniera, Matthew
          Kassawara, Michael Still, Monty Taylor, Nermina Miller, Nigel
          Williams, Phil Hopkins, Russell Bryant, Sahid Orentino Ferdjaoui,
          Sandy Walsh, Sascha Peilicke, Sean M. Collins, Sergey Lukjanov,
          Shilla Saebi, Stephen Gordon, Summer Long, Uwe Stuehler, Vaibhav
          Bhatkar, Veronica Musso, Ying Chun "Daisy" Guo, Zhengguang Ou, and
          ZhiQiang Fan.</para>
        </listitem>
      </varlistentry>
    </variablelist>
  </section>

  <section xml:id="how-to-contribute-to-ops-guide">
    <title>How to Contribute to This Book</title>

    <para>The genesis of this book was an in-person event, but now that the
    book is in your hands, we want you to contribute to it. OpenStack
    documentation follows the coding principles of iterative work, with bug
    logging, investigating, and fixing. We also store the source content on
    GitHub and invite collaborators through the OpenStack Gerrit installation,
    which offers reviews. For the O'Reilly edition of this book, we are using
    the company's Atlas system, which also stores source content on GitHub and
    enables collaboration among contributors.</para>

    <para>Learn more about how to contribute to the OpenStack docs at <link
    xlink:href="http://opsgui.de/1eLCK10">Documentation How To</link>.</para>

    <para>If you find a bug and can't fix it or aren't sure it's really a doc
    bug, log a bug at <link xlink:href="http://opsgui.de/NPHdoC">OpenStack
    Manuals</link>. Tag the bug under <guilabel>Extra</guilabel> options with
    the <literal>ops-guide</literal> tag to indicate that the bug is in this
    guide. You can assign the bug to yourself if you know how to fix it. Also,
    a member of the OpenStack doc-core team can triage the doc bug.</para>
  </section>

  <?hard-pagebreak ?>

  <section xml:id="conventions_used_in_this_book">
    <title>Conventions Used in This Book</title>

    <para>The following typographical conventions are used in this
    book:</para>

    <variablelist>
      <varlistentry>
        <term><emphasis>Italic</emphasis></term>

        <listitem>
          <para>Indicates new terms, URLs, email addresses, filenames, and
          file extensions.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><literal>Constant width</literal></term>

        <listitem>
          <para>Used for program listings, as well as within paragraphs to
          refer to program elements such as variable or function names,
          databases, data types, environment variables, statements, and
          keywords.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><userinput>Constant width bold</userinput></term>

        <listitem>
          <para>Shows commands or other text that should be typed literally by
          the user.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><replaceable>Constant width italic</replaceable></term>

        <listitem>
          <para>Shows text that should be replaced with user-supplied values
          or by values determined by context.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Command prompts</term>

        <listitem>
          <para>Commands prefixed with the <literal>#</literal> prompt should
          be executed by the <literal>root</literal> user. These examples can
          also be executed using the <literal>sudo</literal> command, if
          available.</para>

          <para>Commands prefixed with the <literal>$</literal> prompt can be
          executed by any user, including <literal>root</literal>.</para>
        </listitem>
      </varlistentry>
    </variablelist>

    <tip>
      <para>This element signifies a tip or suggestion.</para>
    </tip>

    <note>
      <para>This element signifies a general note.</para>
    </note>

    <warning>
      <para>This element indicates a warning or caution.</para>
    </warning>
  </section>
</preface>