Folder rename, file rename, flattening of directories

Current folder name	New folder name	        Book title
----------------------------------------------------------
basic-install 	        DELETE
cli-guide	        DELETE
common	                common
NEW	                admin-guide-cloud	Cloud Administrators Guide
docbkx-example	        DELETE
openstack-block-storage-admin 	DELETE
openstack-compute-admin 	DELETE
openstack-config 	config-reference	OpenStack Configuration Reference
openstack-ha 	        high-availability-guide	OpenStack High Availabilty Guide
openstack-image	        image-guide	OpenStack Virtual Machine Image Guide
openstack-install 	install-guide	OpenStack Installation Guide
openstack-network-connectivity-admin 	admin-guide-network 	OpenStack Networking Administration Guide
openstack-object-storage-admin 	DELETE
openstack-security 	security-guide	OpenStack Security Guide
openstack-training 	training-guide	OpenStack Training Guide
openstack-user 	        user-guide	OpenStack End User Guide
openstack-user-admin 	user-guide-admin	OpenStack Admin User Guide
glossary	        NEW        	OpenStack Glossary

bug: #1220407

Change-Id: Id5ffc774b966ba7b9a591743a877aa10ab3094c7
author: diane fleming

doc/admin-guide-cloud/ch_compute.xml

@@ -706,14 +706,14 @@ header: Date: Thu, 13 Sep 2012 20:27:36 GMT
                         <para>In OpenStack the base operating system is usually
                                 copied from an image stored in the Glance image
                                 service. This is the most common case and results in
-                                an ephemeral instance which starts from a know
-                                templated state and lose all accumulated state on
+                                an ephemeral instance that starts from a known
+                                template state and loses all accumulated states on
                                 shutdown. It is also possible in special cases to put
                                 an operating system on a persistent "volume" in the
                                 Nova-Volume or Cinder volume system. This gives a more
-                                traditional persistent system that accumulates state
-                                which is preserved across restarts. To get a list of
-                                available images on your system run:
+                                traditional persistent system that accumulates states,
+                                which are preserved across restarts. To get a list of
+                                available images on your system run:</para>
                                 <screen><prompt>$</prompt> <userinput>nova image-list</userinput>
  <computeroutput>
 +--------------------------------------+-------------------------------+--------+--------------------------------------+
@@ -725,7 +725,6 @@ header: Date: Thu, 13 Sep 2012 20:27:36 GMT
 +--------------------------------------+-------------------------------+--------+--------------------------------------+
  </computeroutput>
  </screen>
-                        </para>
                         <para>The displayed image attributes are:</para>
                         <itemizedlist>
                                 <listitem>

doc/admin-guide-cloud/ch_networking.xml

@@ -184,7 +184,7 @@
             <para>Not all OpenStack networking plugins are compatible with all possible OpenStack compute drivers:</para>
 
             <table rules="all">
-                <caption>Plugin Compatability with OpenStack Compute Drivers</caption>
+                <caption>Plugin Compatibility with OpenStack Compute Drivers</caption>
 		<col/>
 		<col/>
 		<col/>
@@ -1967,7 +1967,7 @@ notification_topics = notifications
                             xmlns:svg="http://www.w3.org/2000/svg"
                             xmlns:html="http://www.w3.org/1999/xhtml">OpenStack Configuration
                             Reference</citetitle> . RPC notifications will go to
-                        'notifications.info' queue binded to a topic exchange defined by
+                        'notifications.info' queue bound to a topic exchange defined by
                         'control_exchange' in <filename>neutron.conf</filename>.</para>
         <screen>
                     <computeroutput>
@@ -2003,7 +2003,7 @@ notification_topics = notifications
                 <title>Multiple RPC topics</title>
                 <para>The options below will make OpenStack Networking server send notifications to
           multiple RPC topics. RPC notifications will go to 'notifications_one.info' and
-          'notifications_two.info' queues binded to a topic exchange defined by 'control_exchange'
+          'notifications_two.info' queues bound to a topic exchange defined by 'control_exchange'
           in <filename>neutron.conf</filename>.</para>
         <screen>
                     <computeroutput>
@@ -2171,11 +2171,11 @@ notification_topics = notifications_one,notifications_two
         <para>[2] is the default policy which is always evaluated if an API operation does not match any
             of the policies in policy.json.</para>
         <para>[3] This policy will evaluate successfully if either <emphasis role="italic"
-            >admin_or_owner</emphasis>, or <emphasis role="italic">shared</emphasis> evalutes
+            >admin_or_owner</emphasis>, or <emphasis role="italic">shared</emphasis> evaluates
             successfully.</para>
         <para>[4] This policy will restrict the ability of manipulating the <emphasis role="italic"
             >shared</emphasis> attribute for a network to administrators only.</para>
-        <para>[5] This policy will restrict the ability of manipilating the <emphasis role="italic"
+        <para>[5] This policy will restrict the ability of manipulating the <emphasis role="italic"
             >mac_address</emphasis> attribute for a port only to administrators and the owner of the
             network where the port is attached.</para>
         <para>In some cases, some operations should be restricted to administrators only; therefore, as

doc/admin-guide-cloud/section_volume-migration.xml

@@ -5,14 +5,12 @@
     xmlns:xlink="http://www.w3.org/1999/xlink"
     version="5.0">
             <title>Migrate volumes</title>
-
             <para>The Havana release of OpenStack introduces the ability to
         migrate volumes between backends. Migrating a volume will transparently
         move its data from the volume's current backend to a new one. This is an
         administrator function, and can be used for functions including storage
         evacuation (for maintenance or decommissioning), or manual optimizations
         (for example, performance, reliability, or cost).</para>
-
             <para>There are three possible flows for a migration:</para>
             <orderedlist>
                 <listitem>
@@ -37,14 +35,12 @@
                     the Block Storage service will create a new volume,
                     and call Compute to copy the data from the original
                     to the new volume.  Currently this is supported only
-                    by Compute's libvirt driver.</para>
+                    by the Compute libvirt driver.</para>
                 </listitem>
             </orderedlist>
-
             <para>As an example, we will show a scenario with two LVM
             backends, and migrate an attached volume from one to the
             other. This will use the 3rd migration flow.</para>
-
             <para>First, we can list the available backends:
                 <screen>
 <prompt>$</prompt> <userinput>cinder-manage host list</userinput>
@@ -54,9 +50,8 @@ server2@lvmstorage-2    zone1
                     </computeroutput>
                 </screen>
             </para>
-
             <para>Next, as the admin user, we can see the current status
-            of the volume (replace the example ID with your own):
+            of the volume (replace the example ID with your own):</para>
                 <screen>
 <prompt>$</prompt> <userinput>cinder show 6088f80a-f116-4331-ad48-9afb0dfb196c</userinput>
                     <computeroutput>
@@ -83,8 +78,6 @@ server2@lvmstorage-2    zone1
 +--------------------------------+--------------------------------------+
                     </computeroutput>
                 </screen>
-            </para>
-
             <para>Of special note are the following attributes:</para>
             <itemizedlist>
                 <listitem>
@@ -115,20 +108,18 @@ server2@lvmstorage-2    zone1
                     <literal>name_id</literal> attribute.</para>
                 </listitem>
             </itemizedlist>
-
             <para>Now we will migrate this volume to the second LVM backend:
                 <screen>
 <prompt>$</prompt> <userinput>cinder migrate 6088f80a-f116-4331-ad48-9afb0dfb196c server2@lvmstorage-2</userinput>
                 </screen>
             </para>
-
             <para>We can use the <command>cinder show</command> command to see
         the status of the migration. While migrating, the
             <literal>migstat</literal> attribute will show states such as
             <literal>migrating</literal> or <literal>completing</literal>. On
         error, <literal>migstat</literal> will be set to <literal>None</literal>
         and the <literal>host</literal> attribute will show the original host.
-        On success, in our example, the output would look like:
+        On success, in our example, the output would look like:</para>
         <screen><computeroutput>
 +--------------------------------+--------------------------------------+
 |            Property            |                Value                 |
@@ -152,15 +143,12 @@ server2@lvmstorage-2    zone1
 |          volume_type           |                 None                 |
 +--------------------------------+--------------------------------------+
                 </computeroutput></screen>
-    </para>
-
             <para>Note that <literal>migstat</literal> is None,
             <literal>host</literal> is the new host, and
             <literal>name_id</literal> holds the ID of the volume
             created by the migration. If we were to look at the second
             LVM backend, we would find the logical volume
             <literal>volume-133d1f56-9ffc-4f57-8798-d5217d851862</literal>.</para>
-
             <note>
                 <para>The migration will not be visible to non-admin
                 users (for example, via the volume's
@@ -170,7 +158,6 @@ server2@lvmstorage-2    zone1
                 volume. If a user performs such an action during a
                 migration, an error will be returned.</para>
             </note>
-
             <note>
                 <para>Migrating volumes that have snapshots is currently
                 not allowed.</para>

doc/admin-guide-network/app_demo_multi_dhcp_agents.xml

@@ -460,9 +460,9 @@ export OS_AUTH_URL=http://controlnode:5000/v2.0/</programlisting>
                             </listitem>
                             <listitem>
                               <procedure>
-                                <title>Testing the HA</title>
+                                <title>To test the HA</title>
                                 <step>
-                                  <para>Login to the <literal>'myserver4'</literal>
+                                  <para>Log in to the <literal>'myserver4'</literal>
                                     VM, and run <literal>'udhcpc'</literal>, <literal>'dhclient'</literal> or other DHCP client.
                                   </para>
                                 </step>

doc/admin-guide-network/bk-networking-admin-guide.xml

@@ -41,11 +41,9 @@
             </annotation>
         </legalnotice>
         <abstract>
-            <para>This document is for administrators
-                interested in running the OpenStack Networking Service.</para>
-        </abstract>
-
-        <revhistory>
+            <para>This document is for administrators who run the
+                OpenStack Networking Service.</para>
+        </abstract><revhistory>
             <!-- ... continue adding more revisions here as you change this document using the markup shown below... -->
             <revision>
                 <date>2013-06-05</date>
@@ -120,9 +118,7 @@
                         </listitem>
                     </itemizedlist>
                 </revdescription>
-            </revision>
-
-            <revision>
+            </revision>    <revision>
                 <date>2012-09-18</date>
                 <revdescription>
                     <itemizedlist spacing="compact">

doc/admin-guide-network/ch_auth.xml

@@ -0,0 +1,183 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter xmlns="http://docbook.org/ns/docbook"
+    xmlns:xi="http://www.w3.org/2001/XInclude"
+    xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
+    xml:id="ch_auth">
+    <title>Authentication and Authorization</title>
+    <para>OpenStack Networking uses the OpenStack Identity Service
+        (project name keystone) as the default authentication service.
+        When OpenStack Identity is enabled, users who submit requests
+        to the OpenStack Networking service must provide an
+        authentication token in X-Auth-Token request header. Users get
+        this token by authenticating with the OpenStack Identity
+        endpoint. For more information about authentication with
+        OpenStack Identity Service, see the OpenStack Identity
+        documentation.</para>
+    <para>When OpenStack Identity is enabled, it is not mandatory to
+        specify tenant_id for resources in create requests because the
+        tenant identifier is derived from the authentication
+        token.</para>
+    <note>
+        <para>The default authorization settings only allow
+            administrative users to create resources on behalf of a
+            different tenant.</para>
+    </note>
+    <para>OpenStack Networking uses information received from
+        OpenStack Identity to authorize user requests. OpenStack
+        Networking handles two kind of authorization policies:</para>
+    <itemizedlist>
+        <listitem>
+            <para><emphasis role="bold">Operation-based</emphasis>:
+                policies specify access criteria for specific
+                operations, possibly with fine-grained control over
+                specific attributes; </para>
+        </listitem>
+        <listitem>
+            <para><emphasis role="bold">Resource-based:</emphasis>
+                whether access to specific resource might be granted
+                or not according to the permissions configured for the
+                resource (currently available only for the network
+                resource). The actual authorization policies enforced
+                in OpenStack Networking might vary from deployment to
+                deployment.</para>
+        </listitem>
+    </itemizedlist>
+    <para>The policy engine reads entries from the <emphasis
+            role="italic">policy.json</emphasis> file. The actual
+        location of this file might vary from distribution to
+        distribution. Entries can be updated while the system is
+        running, and no service restart is required. That is to say,
+        every time the policy file is updated, the policies will be
+        automatically reloaded. Currently the only way of updating
+        such policies is to edit the policy file. </para>
+    <para>In this section, the terms "policy" and "rule" both refer to
+        objects that are specified in the same way in the policy file;
+        there are no syntax differences between a rule and a policy. A
+        policy is something that is matched directly from the
+        OpenStack Networking policy engine. A rule is a component of
+        policies, which are then evaluated. For instance in
+            <code>create_subnet: [["admin_or_network_owner"]]</code>,
+            <emphasis role="italic">create_subnet</emphasis> is a
+        policy, and <emphasis role="italic"
+            >admin_or_network_owner</emphasis> is a rule.</para>
+    <para>Policies are triggered by the OpenStack Networking policy
+        engine whenever one of them matches an OpenStack Networking
+        API operation or a specific attribute being used in a given
+        operation. For instance the <code>create_subnet</code> policy
+        is triggered every time a <code>POST /v2.0/subnets</code>
+        request is sent to the OpenStack Networking server; on the
+        other hand <code>create_network:shared</code> is triggered
+        every time the <emphasis role="italic">shared</emphasis>
+        attribute is explicitly specified (and set to a value
+        different from its default) in a <code>POST
+            /v2.0/networks</code> request. It is also worth mentioning
+        that policies can be also related to specific API extensions;
+        for instance <code>extension:provider_network:set</code> will
+        be triggered if the attributes defined by the Provider Network
+        extensions are specified in an API request.</para>
+    <para>An authorization policy can be composed by one or more
+        rules. If more rules are specified, evaluation policy will be
+        successful if any of the rules evaluates successfully; if an
+        API operation matches multiple policies, all the policies must
+        evaluate successfully. Also, authorization rules are
+        recursive. Once a rule is matched, it can be resolved to
+        another rule until a terminal rule is reached.</para>
+    <para>The OpenStack Networking policy engine currently defines the
+        following kinds of terminal rules:</para>
+    <itemizedlist>
+        <listitem>
+            <para><emphasis role="bold">Role-based rules</emphasis>:
+                evaluate successfully if the user submitting the
+                request has the specified role. For instance
+                    <code>"role:admin"</code>is successful if the user
+                submitting the request is an administrator.</para>
+        </listitem>
+        <listitem>
+            <para><emphasis role="bold">Field-based rules:
+                </emphasis>evaluate successfully if a field of the
+                resource specified in the current request matches a
+                specific value. For instance
+                    <code>"field:networks:shared=True"</code> is
+                successful if the attribute <emphasis role="italic"
+                    >shared</emphasis> of the <emphasis role="italic"
+                    >network</emphasis> resource is set to
+                true.</para>
+        </listitem>
+        <listitem>
+            <para><emphasis role="bold">Generic rules:</emphasis>
+                compare an attribute in the resource with an attribute
+                extracted from the user's security credentials and
+                evaluates successfully if the comparison is
+                successful. For instance
+                    <code>"tenant_id:%(tenant_id)s"</code> is
+                successful if the tenant identifier in the resource is
+                equal to the tenant identifier of the user submitting
+                the request.</para>
+        </listitem>
+    </itemizedlist>
+    <para>The following is an extract from the default policy.json
+        file:</para>
+    <programlisting language="bash">{
+[1] "admin_or_owner": [["role:admin"], ["tenant_id:%(tenant_id)s"]],
+    "admin_or_network_owner": [["role:admin"], ["tenant_id:%(network_tenant_id)s"]],
+    "admin_only": [["role:admin"]], "regular_user": [],
+    "shared": [["field:networks:shared=True"]],
+[2] "default": [["rule:admin_or_owner"]],
+    "create_subnet": [["rule:admin_or_network_owner"]],
+    "get_subnet": [["rule:admin_or_owner"], ["rule:shared"]],
+    "update_subnet": [["rule:admin_or_network_owner"]],
+    "delete_subnet": [["rule:admin_or_network_owner"]],
+    "create_network": [],
+[3] "get_network": [["rule:admin_or_owner"], ["rule:shared"]],
+[4] "create_network:shared": [["rule:admin_only"]],
+    "update_network": [["rule:admin_or_owner"]],
+    "delete_network": [["rule:admin_or_owner"]],
+    "create_port": [],
+[5] "create_port:mac_address": [["rule:admin_or_network_owner"]],
+    "create_port:fixed_ips": [["rule:admin_or_network_owner"]],
+    "get_port": [["rule:admin_or_owner"]],
+    "update_port": [["rule:admin_or_owner"]],
+    "delete_port": [["rule:admin_or_owner"]]
+}</programlisting>
+    <para>[1] is a rule which evaluates successfully if the current
+        user is an administrator or the owner of the resource
+        specified in the request (tenant identifier is equal).</para>
+    <para>[2] is the default policy which is always evaluated if an
+        API operation does not match any of the policies in
+        policy.json.</para>
+    <para>[3] This policy will evaluate successfully if either
+            <emphasis role="italic">admin_or_owner</emphasis>, or
+            <emphasis role="italic">shared</emphasis> evaluates
+        successfully.</para>
+    <para>[4] This policy will restrict the ability of manipulating
+        the <emphasis role="italic">shared</emphasis> attribute for a
+        network to administrators only.</para>
+    <para>[5] This policy will restrict the ability of manipulating
+        the <emphasis role="italic">mac_address</emphasis> attribute
+        for a port only to administrators and the owner of the network
+        where the port is attached.</para>
+    <para>In some cases, some operations should be restricted to
+        administrators only; therefore, as a further example, let us
+        consider how this sample policy file should be modified in a
+        scenario where tenants are allowed only to define networks and
+        see their resources, and all the other operations can be
+        performed only in an administrative context:</para>
+    <programlisting language="bash">{
+    "admin_or_owner": [["role:admin"], ["tenant_id:%(tenant_id)s"]],
+    "admin_only": [["role:admin"]], "regular_user": [],
+    "default": [["rule:admin_only"]],
+    "create_subnet": [["rule:admin_only"]],
+    "get_subnet": [["rule:admin_or_owner"]],
+    "update_subnet": [["rule:admin_only"]],
+    "delete_subnet": [["rule:admin_only"]],
+    "create_network": [],
+    "get_network": [["rule:admin_or_owner"]],
+    "create_network:shared": [["rule:admin_only"]],
+    "update_network": [["rule:admin_or_owner"]],
+    "delete_network": [["rule:admin_or_owner"]],
+    "create_port": [["rule:admin_only"]],
+    "get_port": [["rule:admin_or_owner"]],
+    "update_port": [["rule:admin_only"]],
+    "delete_port": [["rule:admin_only"]]
+}</programlisting>
+</chapter>

doc/common/app_command_reference.xml

@@ -16,24 +16,24 @@
         xml:id="nova_summary" label="A">
         <title>Command reference</title>
         <xi:include
-                href="../openstack-user/src/section_keystone_cli_commands.xml"/>
+                href="../user-guide/section_keystone_cli_commands.xml"/>
         <?hard page-break?>
         <xi:include
-                href="../openstack-user/src/section_glance_cli_commands.xml"/>
+                href="../user-guide/section_glance_cli_commands.xml"/>
         <?hard page-break?>
         <xi:include
-                href="../openstack-user/src/section_neutron_cli_commands.xml"/>
+                href="../user-guide/section_neutron_cli_commands.xml"/>
         <?hard page-break?>
         <xi:include
-                href="../openstack-user/src/section_nova_cli_commands.xml"/>
+                href="../user-guide/section_nova_cli_commands.xml"/>
         <?hard page-break?>
         <xi:include
-                href="../openstack-user/src/section_cinder_cli_commands.xml"/>
+                href="../user-guide/section_cinder_cli_commands.xml"/>
         <?hard page-break?>
         <xi:include
-                href="../openstack-user/src/section_swift_cli_commands.xml"/>
+                href="../user-guide/section_swift_cli_commands.xml"/>
         <?hard page-break?>
         <xi:include
-                href="../openstack-user/src/section_heat_cli_commands.xml"
+                href="../user-guide/section_heat_cli_commands.xml"
         />
 </appendix>