swift-ring-builder
(1)
Name
swift-ring-builder - OpenStack Swift ring builder
Synopsis
swift-ring-builder <builder_file> <commands> <arguments>
<...>
Description
OpenStack Swift swift-ring-builder(1)
NAME
swift-ring-builder - OpenStack Swift ring builder
SYNOPSIS
swift-ring-builder <builder_file> <commands> <arguments>
<...>
DESCRIPTION
The swift-ring-builder utility is used to create, search and
manipulate the swift storage ring. The ring-builder assigns
partitions to devices and writes an optimized Python struc-
ture to a gzipped, pickled file on disk for shipping out to
the servers. The server processes just check the modifica-
tion time of the file occasionally and reload their in-mem-
ory copies of the ring structure as needed. Because of how
the ring-builder manages changes to the ring, using a
slightly older ring usually just means one of the three
replicas for a subset of the partitions will be incorrect,
which can be easily worked around.
The ring-builder also keeps its own builder file with the
ring information and additional data required to build
future rings. It is very important to keep multiple backup
copies of these builder files. One option is to copy the
builder files out to every server while copying the ring
files themselves. Another is to upload the builder files
into the cluster itself. Complete loss of a builder file
will mean creating a new ring from scratch, nearly all par-
titions will end up assigned to different devices, and
therefore nearly all data stored will have to be replicated
to new locations. So, recovery from a builder file loss is
possible, but data will definitely be unreachable for an
extended time.
If invoked as 'swift-ring-builder-safe' the directory con-
taining the builder file provided will be locked (via a
.lock file in the files parent directory). This provides a
basic safe guard against multiple instances of the swift-
ring-builder (or other utilities that observe this lock)
from attempting to write to or read the builder/ring files
while operations are in progress. This can be useful in
environments where ring management has been automated but
the operator still needs to interact with the rings manu-
ally.
SEARCH
<search-value>
Can be of the form:
OpenStack Last change: 8/26/2011 1
OpenStack Swift swift-ring-builder(1)
d<device_id>z<zone>-<ip>:<port>/<device_name>_<meta>
examples:
Any part is optional, but you must include at least
one,
d74 Matches the device id 74
z1 Matches devices in zone 1
1.2.3.4
z1-1.2.3.4 Matches devices in zone 1 with
the ip
1.2.3.4
1.2.3.4 Matches devices in any zone with
the ip
5678
z1:5678 Matches devices in zone 1 using
port
:5678 Matches devices that use port 5678
sdb1
/sdb1 Matches devices with the device
name
data
_shiny Matches devices with shiny in the
meta
the meta data
_'snet: 5.6.7.8' Matches devices with snet:
5.6.7.8 in
::1
[::1] Matches devices in any zone with
the ip
and port 5678
z1-[::1]:5678 Matches devices in zone 1 with
ip ::1
Most specific example:
d74z1-1.2.3.4:5678/sdb1_"snet: 5.6.7.8"
Nerd explanation:
the ip, in which case the - is optional unless
the device id or zone is also included.
All items require their single character prefix
except
COMMANDS
<builder_file>
Shows information about the ring and the devices
within.
OpenStack Last change: 8/26/2011 2
OpenStack Swift swift-ring-builder(1)
search <search-value>
Shows information about matching devices.
add z<zone>-<ip>:<port>/<device_name>_<meta> <weight>
add r<region>z<zone>-<ip>:<port>/<device_name>_<meta>
<weight>
<meta> -w <weight>
add -r <region> -z <zone> -i <ip> -p <port> -d
<device_name> -m
Adds a device to the ring with the given information.
No partitions will be assigned to the new device until
after running 'rebalance'. This is so you can make mul-
tiple device changes and rebalance them all just once.
create <part_power> <replicas> <min_part_hours>
Creates <builder_file> with 2^<part_power> partitions
and <replicas>. <min_part_hours> is number of hours to
restrict moving a partition more than once.
list_parts <search-value> [<search-value>] ..
Returns a 2 column list of all the partitions that are
assigned to any of the devices matching the search val-
ues given. The first column is the assigned partition
number and the second column is the number of device
matches for that partition. The list is ordered from
most number of matches to least. If there are a lot of
devices to match against, this command could take a
while to run.
rebalence
Attempts to rebalance the ring by reassigning parti-
tions that haven't been recently reassigned.
remove <search-value>
Removes the device(s) from the ring. This should nor-
mally just be used for a device that has failed. For a
device you wish to decommission, it's best to set its
weight to 0, wait for it to drain all its data, then
use this remove command. This will not take effect
until after running 'rebalance'. This is so you can
make multiple device changes and rebalance them all
just once.
set_info <search-value> <ip>:<port>/<device_name>_<meta>
Resets the device's information. This information isn't
used to assign partitions, so you can use 'write_ring'
OpenStack Last change: 8/26/2011 3
OpenStack Swift swift-ring-builder(1)
afterward to rewrite the current ring with the newer
device information. Any of the parts are optional in
the final <ip>:<port>/<device_name>_<meta> parameter;
just give what you want to change. For instance
set_info d74 _"snet: 5.6.7.8" would just update the
meta data for device id 74.
set_min_part_hours <hours>
Changes the <min_part_hours> to the given <hours>. This
should be set to however long a full replication/update
cycle takes. We're working on a way to determine this
more easily than scanning logs.
set_weight <search-value> <weight>
Resets the device's weight. No partitions will be reas-
signed to or from the device until after running
'rebalance'. This is so you can make multiple device
changes and rebalance them all just once.
validate
Just runs the validation routines on the ring.
write_ring
Just rewrites the distributable ring file. This is done
automatically after a successful rebalance, so really
this is only useful after one or more 'set_info' calls
when no rebalance is needed but you want to send out
the new device information.
Quick list: add create list_parts rebalance remove search
set_info
set_min_part_hours set_weight validate
write_ring
Exit codes: 0 = ring changed, 1 = ring did not change, 2 =
error
DOCUMENTATION
More in depth documentation about the swift ring and also
OpenStack Swift as a whole can be found at
http://swift.openstack.org/overview_ring.html,
http://swift.openstack.org/admin_guide.html#managing-the-
rings and http://swift.openstack.org
OpenStack Last change: 8/26/2011 4
OpenStack Swift swift-ring-builder(1)
ATTRIBUTES
See attributes(5) for descriptions of the following
attributes:
+---------------+-----------------------+
|ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+---------------+-----------------------+
|Availability | cloud/openstack/swift |
+---------------+-----------------------+
|Stability | Uncommitted |
+---------------+-----------------------+
NOTES
This software was built from source available at
https://java.net/projects/solaris-userland. The original
community source was downloaded from http://launch-
pad.net/swift/havana/1.10.0/+download/swift-1.10.0.tar.gz
Further information about this software can be found on the
open source community website at http://www.openstack.org/.
OpenStack Last change: 8/26/2011 5