swift-ring-builder - OpenStack Swift ring builder
swift-ring-builder <builder_file> <commands> <arguments> <...>
swift-ring-builder(1) 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 structure to a gzipped, pickled file on
disk for shipping out to the servers. The server processes just check
the modification 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 usu-
ally just means one of the three replicas for a subset of the parti-
tions will be incorrect, which can be easily worked around.
The ring-builder also keeps its own builder file with the ring informa-
tion 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 partitions 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 containing 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 manually.
SEARCH
<search-value>
Can be of the form:
d<device_id>z<zone>-<ip>:<port>/<device_name>_<meta>
Any part is optional, but you must include at least one, examples:
d74 Matches the device id 74
z1 Matches devices in zone 1
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
1.2.3.4
z1:5678 Matches devices in zone 1 using port 5678
:5678 Matches devices that use port 5678
/sdb1 Matches devices with the device name sdb1
_shiny Matches devices with shiny in the meta data
_'snet: 5.6.7.8' Matches devices with snet: 5.6.7.8 in the meta
data
[::1] Matches devices in any zone with the ip ::1
z1-[::1]:5678 Matches devices in zone 1 with ip ::1 and port
5678
Most specific example:
d74z1-1.2.3.4:5678/sdb1_"snet: 5.6.7.8"
Nerd explanation:
All items require their single character prefix except the ip,
in which case the - is optional unless the device id or zone is
also included.
COMMANDS
<builder_file>
Shows information about the ring and the devices within.
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>
add -r <region> -z <zone> -i <ip> -p <port> -d <device_name> -m <meta>
-w <weight>
Adds a device to the ring with the given information. No parti-
tions will be assigned to the new device until after running
'rebalance'. This is so you can make multiple device changes and
rebalance them all just once.
create <part_power> <replicas> <min_part_hours>
Creates <builder_file> with 2^<part_power> partitions and <repli-
cas>. <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 values 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 partitions that
haven't been recently reassigned.
remove <search-value>
Removes the device(s) from the ring. This should normally just be
used for a device that has failed. For a device you wish to decom-
mission, 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' afterward to re-
write 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 reassigned 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 automati-
cally 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/over-
view_ring.html, http://swift.openstack.org/admin_guide.html#managing-
the-rings and http://swift.openstack.org
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/kilo/2.3.0/+download/swift-2.3.0.tar.gz
Further information about this software can be found on the open source
community website at http://www.openstack.org/.
OpenStack 8/26/2011 swift-ring-builder(1)