openstack/deb-swift
Code Issues Proposed changes

Misc doc cleanup

Browse Source 
* Change some absolute URLs to internal links
* Fix some bulletted list indentation
* Choose a better lexer for some syntax highlighting
* Use ``inline code`` instead of `italics` for some example command
  lines
* Change some quoted paragraphs that only included inlined code to be
  proper code blocks

Change-Id: Iaaa7eefb690122f5af9dcb1c871358c22335c743
This commit is contained in:
Tim Burke 2017-07-12 12:14:45 -07:00
parent 63c4215994
commit 13a07aa77a
8 changed files with 167 additions and 143 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
doc/source/admin/objectstorage-EC.rst
View File

@ -7,9 +7,7 @@ missing data from a set of original data. In theory, erasure coding uses
less capacity with similar durability characteristics as replicas. less capacity with similar durability characteristics as replicas.
From an application perspective, erasure coding support is transparent. From an application perspective, erasure coding support is transparent.
Object Storage (swift) implements erasure coding as a Storage Policy. Object Storage (swift) implements erasure coding as a Storage Policy.
See `Storage Policies See :doc:`/overview_policies` for more details.
<https://docs.openstack.org/developer/swift/overview_policies.html>`_
for more details.
There is no external API related to erasure coding. Create a container using a There is no external API related to erasure coding. Create a container using a
Storage Policy; the interaction with the cluster is the same as any Storage Policy; the interaction with the cluster is the same as any

3
doc/source/admin/objectstorage-large-objects.rst
View File

@ -30,6 +30,5 @@ The large object is comprised of two types of objects:
To find out more information on large object support, see `Large objects To find out more information on large object support, see `Large objects
<https://docs.openstack.org/user-guide/cli-swift-large-object-creation.html>`_ <https://docs.openstack.org/user-guide/cli-swift-large-object-creation.html>`_
in the OpenStack End User Guide, or `Large Object Support in the OpenStack End User Guide, or :doc:`/overview_large_objects`
<https://docs.openstack.org/developer/swift/overview_large_objects.html>`_
in the developer documentation. in the developer documentation.

8
doc/source/admin/objectstorage-monitoring.rst
View File

@ -4,7 +4,7 @@ Object Storage monitoring
.. note:: .. note::
This section was excerpted from a blog post by `Darrell This section was excerpted from a `blog post by Darrell
Bishop <http://swiftstack.com/blog/2012/04/11/swift-monitoring-with-statsd>`_ and Bishop <http://swiftstack.com/blog/2012/04/11/swift-monitoring-with-statsd>`_ and
has since been edited. has since been edited.
@ -17,8 +17,7 @@ usage and utilization, and so on is necessary, but not sufficient.
Swift Recon Swift Recon
~~~~~~~~~~~ ~~~~~~~~~~~
The Swift Recon middleware (see The Swift Recon middleware (see :ref:`cluster_telemetry_and_monitoring`)
`Defining Storage Policies <https://docs.openstack.org/developer/swift/admin_guide.html#cluster-telemetry-and-monitoring>`_)
provides general machine statistics, such as load average, socket provides general machine statistics, such as load average, socket
statistics, ``/proc/meminfo`` contents, as well as Swift-specific meters: statistics, ``/proc/meminfo`` contents, as well as Swift-specific meters:
@ -127,8 +126,7 @@ after-the-fact log processing, the sending of StatsD meters is
integrated into Object Storage itself. The submitted change set (see integrated into Object Storage itself. The submitted change set (see
`<https://review.openstack.org/#change,6058>`_) currently reports 124 meters `<https://review.openstack.org/#change,6058>`_) currently reports 124 meters
across 15 Object Storage daemons and the tempauth middleware. Details of across 15 Object Storage daemons and the tempauth middleware. Details of
the meters tracked are in the `Administrator's the meters tracked are in the :doc:`/admin_guide`.
Guide <https://docs.openstack.org/developer/swift/admin_guide.html>`_.
The sending of meters is integrated with the logging framework. To The sending of meters is integrated with the logging framework. To
enable, configure ``log_statsd_host`` in the relevant config file. You enable, configure ``log_statsd_host`` in the relevant config file. You

164
doc/source/admin_guide.rst
View File

@ -22,9 +22,9 @@ before planning the upgrade of your existing deployment.
Following is a high level view of the very few steps it takes to configure Following is a high level view of the very few steps it takes to configure
policies once you have decided what you want to do: policies once you have decided what you want to do:
#. Define your policies in ``/etc/swift/swift.conf`` #. Define your policies in ``/etc/swift/swift.conf``
#. Create the corresponding object rings #. Create the corresponding object rings
#. Communicate the names of the Storage Policies to cluster users #. Communicate the names of the Storage Policies to cluster users
For a specific example that takes you through these steps, please see For a specific example that takes you through these steps, please see
:doc:`policies_saio` :doc:`policies_saio`
@ -56,6 +56,8 @@ of the downgrade.
For more information see :doc:`overview_ring`. For more information see :doc:`overview_ring`.
.. highlight:: none
Removing a device from the ring:: Removing a device from the ring::
swift-ring-builder <builder-file> remove <ip_address>/<device_name> swift-ring-builder <builder-file> remove <ip_address>/<device_name>
@ -259,7 +261,7 @@ errors are detected, it will unmount the bad drive, so that Swift can
work around it. The script takes a configuration file with the following work around it. The script takes a configuration file with the following
settings: settings:
[drive-audit] ``[drive-audit]``
================== ============== =========================================== ================== ============== ===========================================
Option Default Description Option Default Description
@ -292,6 +294,8 @@ using a different distro or OS, some care should be taken before using in produc
Preventing Disk Full Scenarios Preventing Disk Full Scenarios
------------------------------ ------------------------------
.. highlight:: cfg
Prevent disk full scenarios by ensuring that the ``proxy-server`` blocks PUT Prevent disk full scenarios by ensuring that the ``proxy-server`` blocks PUT
requests and rsync prevents replication to the specific drives. requests and rsync prevents replication to the specific drives.
@ -373,6 +377,8 @@ included, by specifying ``&include`` in your ``rsync.conf`` file:
Use this in conjunction with a cron job to periodically run the script, for example: Use this in conjunction with a cron job to periodically run the script, for example:
.. highlight:: none
.. code:: .. code::
# /etc/cron.d/devicecheck # /etc/cron.d/devicecheck
@ -408,6 +414,8 @@ object names until they fall on distinct partitions. Last, and repeatedly for
the life of the cluster, we need to run the swift-dispersion-report tool to the life of the cluster, we need to run the swift-dispersion-report tool to
check the health of each of these containers and objects. check the health of each of these containers and objects.
.. highlight:: cfg
These tools need direct access to the entire cluster and to the ring files These tools need direct access to the entire cluster and to the ring files
(installing them on a proxy server will probably do). Both (installing them on a proxy server will probably do). Both
swift-dispersion-populate and swift-dispersion-report use the same swift-dispersion-populate and swift-dispersion-report use the same
@ -419,6 +427,8 @@ configuration file, /etc/swift/dispersion.conf. Example conf file::
auth_key = testing auth_key = testing
endpoint_type = internalURL endpoint_type = internalURL
.. highlight:: none
There are also options for the conf file for specifying the dispersion coverage There are also options for the conf file for specifying the dispersion coverage
(defaults to 1%), retries, concurrency, etc. though usually the defaults are (defaults to 1%), retries, concurrency, etc. though usually the defaults are
fine. If you want to use keystone v3 for authentication there are options like fine. If you want to use keystone v3 for authentication there are options like
@ -512,51 +522,51 @@ described in their respective documentation. The following points should be
considered when selecting the feature that is most appropriate for a particular considered when selecting the feature that is most appropriate for a particular
use case: use case:
#. Global Clusters allows the distribution of object replicas across #. Global Clusters allows the distribution of object replicas across
data-centers to be controlled by the cluster operator on per-policy basis, data-centers to be controlled by the cluster operator on per-policy basis,
since the distribution is determined by the assignment of devices from since the distribution is determined by the assignment of devices from
each data-center in each policy's ring file. With Container Sync the end each data-center in each policy's ring file. With Container Sync the end
user controls the distribution of objects across clusters on a user controls the distribution of objects across clusters on a
per-container basis. per-container basis.
#. Global Clusters requires an operator to coordinate ring deployments across #. Global Clusters requires an operator to coordinate ring deployments across
multiple data-centers. Container Sync allows for independent management of multiple data-centers. Container Sync allows for independent management of
separate Swift clusters in each data-center, and for existing Swift separate Swift clusters in each data-center, and for existing Swift
clusters to be used as peers in Container Sync relationships without clusters to be used as peers in Container Sync relationships without
deploying new policies/rings. deploying new policies/rings.
#. Global Clusters seamlessly supports features that may rely on #. Global Clusters seamlessly supports features that may rely on
cross-container operations such as large objects and versioned writes. cross-container operations such as large objects and versioned writes.
Container Sync requires the end user to ensure that all required Container Sync requires the end user to ensure that all required
containers are sync'd for these features to work in all data-centers. containers are sync'd for these features to work in all data-centers.
#. Global Clusters makes objects available for GET or HEAD requests in both #. Global Clusters makes objects available for GET or HEAD requests in both
data-centers even if a replica of the object has not yet been data-centers even if a replica of the object has not yet been
asynchronously migrated between data-centers, by forwarding requests asynchronously migrated between data-centers, by forwarding requests
between data-centers. Container Sync is unable to serve requests for an between data-centers. Container Sync is unable to serve requests for an
object in a particular data-center until the asynchronous sync process has object in a particular data-center until the asynchronous sync process has
copied the object to that data-center. copied the object to that data-center.
#. Global Clusters may require less storage capacity than Container Sync to #. Global Clusters may require less storage capacity than Container Sync to
achieve equivalent durability of objects in each data-center. Global achieve equivalent durability of objects in each data-center. Global
Clusters can restore replicas that are lost or corrupted in one Clusters can restore replicas that are lost or corrupted in one
data-center using replicas from other data-centers. Container Sync data-center using replicas from other data-centers. Container Sync
requires each data-center to independently manage the durability of requires each data-center to independently manage the durability of
objects, which may result in each data-center storing more replicas than objects, which may result in each data-center storing more replicas than
with Global Clusters. with Global Clusters.
#. Global Clusters execute all account/container metadata updates #. Global Clusters execute all account/container metadata updates
synchronously to account/container replicas in all data-centers, which may synchronously to account/container replicas in all data-centers, which may
incur delays when making updates across WANs. Container Sync only copies incur delays when making updates across WANs. Container Sync only copies
objects between data-centers and all Swift internal traffic is objects between data-centers and all Swift internal traffic is
confined to each data-center. confined to each data-center.
#. Global Clusters does not yet guarantee the availability of objects stored #. Global Clusters does not yet guarantee the availability of objects stored
in Erasure Coded policies when one data-center is offline. With Container in Erasure Coded policies when one data-center is offline. With Container
Sync the availability of objects in each data-center is independent of the Sync the availability of objects in each data-center is independent of the
state of other data-centers once objects have been synced. Container Sync state of other data-centers once objects have been synced. Container Sync
also allows objects to be stored using different policy types in different also allows objects to be stored using different policy types in different
data-centers. data-centers.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Checking handoff partition distribution Checking handoff partition distribution
@ -635,6 +645,8 @@ especially :ref:`swift-recon -r <recon-replication>` how to check replication
stats. stats.
.. _cluster_telemetry_and_monitoring:
-------------------------------- --------------------------------
Cluster Telemetry and Monitoring Cluster Telemetry and Monitoring
-------------------------------- --------------------------------
@ -644,6 +656,8 @@ object servers using the recon server middleware and the swift-recon cli. To do
so update your account, container, or object servers pipelines to include recon so update your account, container, or object servers pipelines to include recon
and add the associated filter config. and add the associated filter config.
.. highlight:: cfg
object-server.conf sample:: object-server.conf sample::
[pipeline:main] [pipeline:main]
@ -671,6 +685,8 @@ account-server.conf sample::
use = egg:swift#recon use = egg:swift#recon
recon_cache_path = /var/cache/swift recon_cache_path = /var/cache/swift
.. highlight:: none
The recon_cache_path simply sets the directory where stats for a few items will The recon_cache_path simply sets the directory where stats for a few items will
be stored. Depending on the method of deployment you may need to create this be stored. Depending on the method of deployment you may need to create this
directory manually and ensure that Swift has read/write access. directory manually and ensure that Swift has read/write access.
@ -782,6 +798,8 @@ For example, to obtain container replication info from all hosts in zone "3"::
Reporting Metrics to StatsD Reporting Metrics to StatsD
--------------------------- ---------------------------
.. highlight:: cfg
If you have a StatsD_ server running, Swift may be configured to send it If you have a StatsD_ server running, Swift may be configured to send it
real-time operational metrics. To enable this, set the following real-time operational metrics. To enable this, set the following
configuration entries (see the sample configuration files):: configuration entries (see the sample configuration files)::
@ -1324,7 +1342,7 @@ found.
Managing Services Managing Services
----------------- -----------------
Swift services are generally managed with `swift-init`. the general usage is Swift services are generally managed with ``swift-init``. the general usage is
``swift-init <service> <command>``, where service is the Swift service to ``swift-init <service> <command>``, where service is the Swift service to
manage (for example object, container, account, proxy) and command is one of: manage (for example object, container, account, proxy) and command is one of:
@ -1340,13 +1358,14 @@ reload Attempt to gracefully restart the service
A graceful shutdown or reload will finish any current requests before A graceful shutdown or reload will finish any current requests before
completely stopping the old service. There is also a special case of completely stopping the old service. There is also a special case of
`swift-init all <command>`, which will run the command for all swift services. ``swift-init all <command>``, which will run the command for all swift
services.
In cases where there are multiple configs for a service, a specific config In cases where there are multiple configs for a service, a specific config
can be managed with ``swift-init <service>.<config> <command>``. can be managed with ``swift-init <service>.<config> <command>``.
For example, when a separate replication network is used, there might be For example, when a separate replication network is used, there might be
`/etc/swift/object-server/public.conf` for the object server and ``/etc/swift/object-server/public.conf`` for the object server and
`/etc/swift/object-server/replication.conf` for the replication services. ``/etc/swift/object-server/replication.conf`` for the replication services.
In this case, the replication services could be restarted with In this case, the replication services could be restarted with
``swift-init object-server.replication restart``. ``swift-init object-server.replication restart``.
@ -1358,13 +1377,16 @@ On system failures, the XFS file system can sometimes truncate files it's
trying to write and produce zero-byte files. The object-auditor will catch trying to write and produce zero-byte files. The object-auditor will catch
these problems but in the case of a system crash it would be advisable to run these problems but in the case of a system crash it would be advisable to run
an extra, less rate limited sweep to check for these specific files. You can an extra, less rate limited sweep to check for these specific files. You can
run this command as follows: run this command as follows::
`swift-object-auditor /path/to/object-server/config/file.conf once -z 1000`
"-z" means to only check for zero-byte files at 1000 files per second. swift-object-auditor /path/to/object-server/config/file.conf once -z 1000
``-z`` means to only check for zero-byte files at 1000 files per second.
At times it is useful to be able to run the object auditor on a specific At times it is useful to be able to run the object auditor on a specific
device or set of devices. You can run the object-auditor as follows: device or set of devices. You can run the object-auditor as follows::
swift-object-auditor /path/to/object-server/config/file.conf once --devices=sda,sdb
swift-object-auditor /path/to/object-server/config/file.conf once --devices=sda,sdb
This will run the object auditor on only the sda and sdb devices. This param This will run the object auditor on only the sda and sdb devices. This param
accepts a comma separated list of values. accepts a comma separated list of values.
@ -1374,11 +1396,12 @@ Object Replicator
----------------- -----------------
At times it is useful to be able to run the object replicator on a specific At times it is useful to be able to run the object replicator on a specific
device or partition. You can run the object-replicator as follows: device or partition. You can run the object-replicator as follows::
swift-object-replicator /path/to/object-server/config/file.conf once --devices=sda,sdb
swift-object-replicator /path/to/object-server/config/file.conf once --devices=sda,sdb
This will run the object replicator on only the sda and sdb devices. You can This will run the object replicator on only the sda and sdb devices. You can
likewise run that command with --partitions. Both params accept a comma likewise run that command with ``--partitions``. Both params accept a comma
separated list of values. If both are specified they will be ANDed together. separated list of values. If both are specified they will be ANDed together.
These can only be run in "once" mode. These can only be run in "once" mode.
@ -1389,8 +1412,8 @@ Swift Orphans
Swift Orphans are processes left over after a reload of a Swift server. Swift Orphans are processes left over after a reload of a Swift server.
For example, when upgrading a proxy server you would probably finish For example, when upgrading a proxy server you would probably finish
with a `swift-init proxy-server reload` or `/etc/init.d/swift-proxy with a ``swift-init proxy-server reload`` or ``/etc/init.d/swift-proxy
reload`. This kills the parent proxy server process and leaves the reload``. This kills the parent proxy server process and leaves the
child processes running to finish processing whatever requests they child processes running to finish processing whatever requests they
might be handling at the time. It then starts up a new parent proxy might be handling at the time. It then starts up a new parent proxy
server process and its children to handle new incoming requests. This server process and its children to handle new incoming requests. This
@ -1400,16 +1423,16 @@ The orphaned child processes may take a while to exit, depending on
the length of the requests they were handling. However, sometimes an the length of the requests they were handling. However, sometimes an
old process can be hung up due to some bug or hardware issue. In these old process can be hung up due to some bug or hardware issue. In these
cases, these orphaned processes will hang around cases, these orphaned processes will hang around
forever. `swift-orphans` can be used to find and kill these orphans. forever. ``swift-orphans`` can be used to find and kill these orphans.
`swift-orphans` with no arguments will just list the orphans it finds ``swift-orphans`` with no arguments will just list the orphans it finds
that were started more than 24 hours ago. You shouldn't really check that were started more than 24 hours ago. You shouldn't really check
for orphans until 24 hours after you perform a reload, as some for orphans until 24 hours after you perform a reload, as some
requests can take a long time to process. `swift-orphans -k TERM` will requests can take a long time to process. ``swift-orphans -k TERM`` will
send the SIG_TERM signal to the orphans processes, or you can `kill send the SIG_TERM signal to the orphans processes, or you can ``kill
-TERM` the pids yourself if you prefer. -TERM`` the pids yourself if you prefer.
You can run `swift-orphans --help` for more options. You can run ``swift-orphans --help`` for more options.
------------ ------------
@ -1420,11 +1443,11 @@ Swift Oldies are processes that have just been around for a long
time. There's nothing necessarily wrong with this, but it might time. There's nothing necessarily wrong with this, but it might
indicate a hung process if you regularly upgrade and reload/restart indicate a hung process if you regularly upgrade and reload/restart
services. You might have so many servers that you don't notice when a services. You might have so many servers that you don't notice when a
reload/restart fails; `swift-oldies` can help with this. reload/restart fails; ``swift-oldies`` can help with this.
For example, if you upgraded and reloaded/restarted everything 2 days For example, if you upgraded and reloaded/restarted everything 2 days
ago, and you've already cleaned up any orphans with `swift-orphans`, ago, and you've already cleaned up any orphans with ``swift-orphans``,
you can run `swift-oldies -a 48` to find any Swift processes still you can run ``swift-oldies -a 48`` to find any Swift processes still
around that were started more than 2 days ago and then investigate around that were started more than 2 days ago and then investigate
them accordingly. them accordingly.
@ -1436,7 +1459,7 @@ Custom Log Handlers
Swift supports setting up custom log handlers for services by specifying a Swift supports setting up custom log handlers for services by specifying a
comma-separated list of functions to invoke when logging is setup. It does so comma-separated list of functions to invoke when logging is setup. It does so
via the `log_custom_handlers` configuration option. Logger hooks invoked are via the ``log_custom_handlers`` configuration option. Logger hooks invoked are
passed the same arguments as Swift's get_logger function (as well as the passed the same arguments as Swift's get_logger function (as well as the
getLogger and LogAdapter object): getLogger and LogAdapter object):
@ -1470,7 +1493,6 @@ See :ref:`custom-logger-hooks-label` for sample use cases.
Securing OpenStack Swift Securing OpenStack Swift
------------------------ ------------------------
Please refer to the security guides at: Please refer to the security guide at http://docs.openstack.org/security-guide
and in particular the `Object Storage
* http://docs.openstack.org/sec/ <http://docs.openstack.org/security-guide/object-storage.html>`__ section.
* http://docs.openstack.org/security-guide/content/object-storage.html

31
doc/source/associated_projects.rst
View File

@ -3,30 +3,31 @@
Associated Projects Associated Projects
=================== ===================
.. _application-bindings:
Application Bindings Application Bindings
-------------------- --------------------
* OpenStack supported binding: * OpenStack supported binding:
* `Python-SwiftClient <http://pypi.python.org/pypi/python-swiftclient>`_ * `Python-SwiftClient <http://pypi.python.org/pypi/python-swiftclient>`_
* Unofficial libraries and bindings: * Unofficial libraries and bindings:
* `PHP-opencloud <http://php-opencloud.com>`_ - Official Rackspace PHP bindings that should work for other Swift deployments too. * `PHP-opencloud <http://php-opencloud.com>`_ - Official Rackspace PHP bindings that should work for other Swift deployments too.
* `PyRAX <https://github.com/rackspace/pyrax>`_ - Official Rackspace Python bindings for CloudFiles that should work for other Swift deployments too. * `PyRAX <https://github.com/rackspace/pyrax>`_ - Official Rackspace Python bindings for CloudFiles that should work for other Swift deployments too.
* `openstack.net <https://github.com/rackspace/openstack.net/>`_ - Official Rackspace .NET bindings that should work for other Swift deployments too. * `openstack.net <https://github.com/rackspace/openstack.net/>`_ - Official Rackspace .NET bindings that should work for other Swift deployments too.
* `RSwift <https://github.com/pandemicsyn/RSwift>`_ - R API bindings. * `RSwift <https://github.com/pandemicsyn/RSwift>`_ - R API bindings.
* `Go language bindings <https://github.com/ncw/swift>`_ * `Go language bindings <https://github.com/ncw/swift>`_
* `supload <https://github.com/selectel/supload>`_ - Bash script to upload file to cloud storage based on OpenStack Swift API. * `supload <https://github.com/selectel/supload>`_ - Bash script to upload file to cloud storage based on OpenStack Swift API.
* `libcloud <http://libcloud.apache.org>`_ - Apache Libcloud - a unified interface in Python for different clouds with OpenStack Swift support. * `libcloud <http://libcloud.apache.org>`_ - Apache Libcloud - a unified interface in Python for different clouds with OpenStack Swift support.
* `SwiftBox <https://github.com/suniln/SwiftBox>`_ - C# library using RestSharp * `SwiftBox <https://github.com/suniln/SwiftBox>`_ - C# library using RestSharp
* `jclouds <http://jclouds.incubator.apache.org/documentation/quickstart/openstack/>`_ - Java library offering bindings for all OpenStack projects * `jclouds <http://jclouds.incubator.apache.org/documentation/quickstart/openstack/>`_ - Java library offering bindings for all OpenStack projects
* `java-openstack-swift <https://github.com/dkocher/java-openstack-swift>`_ - Java bindings for OpenStack Swift * `java-openstack-swift <https://github.com/dkocher/java-openstack-swift>`_ - Java bindings for OpenStack Swift
* `swift_client <https://github.com/mrkamel/swift_client>`_ - Small but powerful Ruby client to interact with OpenStack Swift * `swift_client <https://github.com/mrkamel/swift_client>`_ - Small but powerful Ruby client to interact with OpenStack Swift
* `nightcrawler_swift <https://github.com/tulios/nightcrawler_swift>`_ - This Ruby gem teleports your assets to a OpenStack Swift bucket/container * `nightcrawler_swift <https://github.com/tulios/nightcrawler_swift>`_ - This Ruby gem teleports your assets to a OpenStack Swift bucket/container
* `swift storage <https://rubygems.org/gems/swift-storage>`_ - Simple OpenStack Swift storage client. * `swift storage <https://rubygems.org/gems/swift-storage>`_ - Simple OpenStack Swift storage client.
* `javaswift <http://javaswift.org/>`_ - Collection of Java tools for Swift * `javaswift <http://javaswift.org/>`_ - Collection of Java tools for Swift
Authentication Authentication
-------------- --------------

92
doc/source/first_contribution_swift.rst
View File

@ -6,10 +6,12 @@ First Contribution to Swift
Getting Swift Getting Swift
------------- -------------
Swift's source code is hosted on github and managed with git. The current .. highlight: none
trunk can be checked out like this:
``git clone https://github.com/openstack/swift.git`` Swift's source code is hosted on github and managed with git. The current
trunk can be checked out like this::
git clone https://github.com/openstack/swift.git
This will clone the Swift repository under your account. This will clone the Swift repository under your account.
@ -25,7 +27,7 @@ Prebuilt packages for Ubuntu and RHEL variants are available.
Source Control Setup Source Control Setup
-------------------- --------------------
Swift uses `git` for source control. The OpenStack Swift uses ``git`` for source control. The OpenStack
`Developer's Guide <http://docs.openstack.org/infra/manual/developers.html>`_ `Developer's Guide <http://docs.openstack.org/infra/manual/developers.html>`_
describes the steps for setting up Git and all the necessary accounts for describes the steps for setting up Git and all the necessary accounts for
contributing code to Swift. contributing code to Swift.
@ -41,13 +43,13 @@ changes to Swift.
Testing Testing
------- -------
The :doc:`Development Guidelines <development_guidelines>` describes the testing The :doc:`Development Guidelines <development_guidelines>` describe the testing
requirements before submitting Swift code. requirements before submitting Swift code.
In summary, you can execute tox from the swift home directory (where you In summary, you can execute tox from the swift home directory (where you
checked out the source code): checked out the source code)::
``tox`` tox
Tox will present tests results. Notice that in the beginning, it is very common Tox will present tests results. Notice that in the beginning, it is very common
to break many coding style guidelines. to break many coding style guidelines.
@ -58,65 +60,67 @@ Proposing changes to Swift
The OpenStack The OpenStack
`Developer's Guide <http://docs.openstack.org/infra/manual/developers.html>`_ `Developer's Guide <http://docs.openstack.org/infra/manual/developers.html>`_
describes the most common `git` commands that you will need. describes the most common ``git`` commands that you will need.
Following is a list of the commands that you need to know for your first Following is a list of the commands that you need to know for your first
contribution to Swift: contribution to Swift:
To clone a copy of Swift: To clone a copy of Swift::
``git clone https://github.com/openstack/swift.git`` git clone https://github.com/openstack/swift.git
Under the swift directory, set up the Gerrit repository. The following command Under the swift directory, set up the Gerrit repository. The following command
configures the repository to know about Gerrit and makes the Change-Id commit configures the repository to know about Gerrit and installs the ``Change-Id``
hook get installed. You only need to do this once: commit hook. You only need to do this once::
``git review -s`` git review -s
To create your development branch (substitute branch_name for a name of your To create your development branch (substitute branch_name for a name of your
choice: choice:
``git checkout -b <branch_name>`` git checkout -b <branch_name>
To check the files that have been updated in your branch: To check the files that have been updated in your branch::
``git status`` git status
To check the differences between your branch and the repository: To check the differences between your branch and the repository::
``git diff`` git diff
Assuming you have not added new files, you commit all your changes using: Assuming you have not added new files, you commit all your changes using::
``git commit -a`` git commit -a
Read the `Summary of Git commit message structure <https://wiki.openstack.org/wiki/GitCommitMessages?%22Summary%20of%20Git%20commit%20message%20structure%22#Summary_of_Git_commit_message_structure>`_ Read the `Summary of Git commit message structure <https://wiki.openstack.org/wiki/GitCommitMessages?%22Summary%20of%20Git%20commit%20message%20structure%22#Summary_of_Git_commit_message_structure>`_
for best practices on writing the commit message. When you are ready to send for best practices on writing the commit message. When you are ready to send
your changes for review use: your changes for review use::
``git review`` git review
If successful, Git response message will contain a URL you can use to track your If successful, Git response message will contain a URL you can use to track your
changes. changes.
If you need to make further changes to the same review, you can commit them If you need to make further changes to the same review, you can commit them
using: using::
``git commit -a --amend`` git commit -a --amend
This will commit the changes under the same set of changes you issued earlier. This will commit the changes under the same set of changes you issued earlier.
Notice that in order to send your latest version for review, you will still Notice that in order to send your latest version for review, you will still
need to call: need to call::
``git review`` git review
--------------------- ---------------------
Tracking your changes Tracking your changes
--------------------- ---------------------
After you proposed your changes to Swift, you can track the review in: After proposing changes to Swift, you can track them at
https://review.openstack.org. After logging in, you will see a dashboard of
* `<https://review.openstack.org>`_ "Outgoing reviews" for changes you have proposed, "Incoming reviews" for
changes you are reviewing, and "Recently closed" changes for which you were
either a reviewer or owner.
.. _post-rebase-instructions: .. _post-rebase-instructions:
@ -126,23 +130,22 @@ Post rebase instructions
After rebasing, the following steps should be performed to rebuild the swift After rebasing, the following steps should be performed to rebuild the swift
installation. Note that these commands should be performed from the root of the installation. Note that these commands should be performed from the root of the
swift repo directory (e.g. $HOME/swift/): swift repo directory (e.g. ``$HOME/swift/``)::
``sudo python setup.py develop`` sudo python setup.py develop
sudo pip install -r test-requirements.txt
``sudo pip install -r test-requirements.txt``
If using TOX, depending on the changes made during the rebase, you may need to If using TOX, depending on the changes made during the rebase, you may need to
rebuild the TOX environment (generally this will be the case if rebuild the TOX environment (generally this will be the case if
test-requirements.txt was updated such that a new version of a package is test-requirements.txt was updated such that a new version of a package is
required), this can be accomplished using the '-r' argument to the TOX cli: required), this can be accomplished using the ``-r`` argument to the TOX cli::
``tox -r`` tox -r
You can include any of the other TOX arguments as well, for example, to run the You can include any of the other TOX arguments as well, for example, to run the
pep8 suite and rebuild the TOX environment the following can be used: pep8 suite and rebuild the TOX environment the following can be used::
``tox -r -e pep8`` tox -r -e pep8
The rebuild option only needs to be specified once for a particular build (e.g. The rebuild option only needs to be specified once for a particular build (e.g.
pep8), that is further invocations of the same build will not require this pep8), that is further invocations of the same build will not require this
@ -153,9 +156,9 @@ Troubleshooting
--------------- ---------------
You may run into the following errors when starting Swift if you rebase You may run into the following errors when starting Swift if you rebase
your commit using: your commit using::
``git rebase`` git rebase
.. code-block:: python .. code-block:: python
@ -171,7 +174,8 @@ your commit using:
File "/usr/lib/python2.7/dist-packages/pkg_resources.py", line 628, in resolve File "/usr/lib/python2.7/dist-packages/pkg_resources.py", line 628, in resolve
raise DistributionNotFound(req) raise DistributionNotFound(req)
pkg_resources.DistributionNotFound: swift==2.3.1.devXXX pkg_resources.DistributionNotFound: swift==2.3.1.devXXX
(where XXX represents a dev version of Swift).
(where XXX represents a dev version of Swift).
.. code-block:: python .. code-block:: python
@ -198,7 +202,7 @@ your commit using:
for prot in protocol_options] or '(no entry points)')))) for prot in protocol_options] or '(no entry points)'))))
LookupError: Entry point 'versioned_writes' not found in egg 'swift' (dir: /home/swift/swift; protocols: paste.filter_factory, paste.filter_app_factory; entry_points: ) LookupError: Entry point 'versioned_writes' not found in egg 'swift' (dir: /home/swift/swift; protocols: paste.filter_factory, paste.filter_app_factory; entry_points: )
This happens because `git rebase` will retrieve code for a different version of This happens because ``git rebase`` will retrieve code for a different version
Swift in the development stream, but the start scripts under `/usr/local/bin` have of Swift in the development stream, but the start scripts under
not been updated. The solution is to follow the steps described in the ``/usr/local/bin`` have not been updated. The solution is to follow the steps
:ref:`post-rebase-instructions` section. described in the :ref:`post-rebase-instructions` section.

2
doc/source/getting_started.rst
View File

@ -35,7 +35,7 @@ following docs will be useful:
CLI client and SDK library CLI client and SDK library
-------------------------- --------------------------
There are many clients in the `ecosystem <http://docs.openstack.org/developer/swift/associated_projects.html#application-bindings>`_. The official CLI There are many clients in the :ref:`ecosystem <application-bindings>`. The official CLI
and SDK is python-swiftclient. and SDK is python-swiftclient.
* `Source code <https://github.com/openstack/python-swiftclient>`_ * `Source code <https://github.com/openstack/python-swiftclient>`_

6
doc/source/howto_installmultinode.rst
View File

@ -9,5 +9,7 @@ for the most up-to-date documentation.
Current Install Guides Current Install Guides
---------------------- ----------------------
* `Object Storage installation guide for OpenStack Ocata <https://docs.openstack.org/project-install-guide/object-storage/ocata/>`_ * `Object Storage installation guide for OpenStack Ocata
* `Object Storage installation guide for OpenStack Newton <https://docs.openstack.org/project-install-guide/object-storage/newton/>`_ <https://docs.openstack.org/project-install-guide/object-storage/ocata/>`__
* `Object Storage installation guide for OpenStack Newton
<https://docs.openstack.org/project-install-guide/object-storage/newton/>`__