221 lines
7.6 KiB
Groff
221 lines
7.6 KiB
Groff
.\"
|
|
.\" Author: Joao Marcelo Martins <marcelo.martins@rackspace.com> or <btorch@gmail.com>
|
|
.\" Copyright (c) 2010-2011 OpenStack Foundation.
|
|
.\"
|
|
.\" Licensed under the Apache License, Version 2.0 (the "License");
|
|
.\" you may not use this file except in compliance with the License.
|
|
.\" You may obtain a copy of the License at
|
|
.\"
|
|
.\" http://www.apache.org/licenses/LICENSE-2.0
|
|
.\"
|
|
.\" Unless required by applicable law or agreed to in writing, software
|
|
.\" distributed under the License is distributed on an "AS IS" BASIS,
|
|
.\" WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
|
.\" implied.
|
|
.\" See the License for the specific language governing permissions and
|
|
.\" limitations under the License.
|
|
.\"
|
|
.TH swift-ring-builder 1 "8/26/2011" "Linux" "OpenStack Swift"
|
|
|
|
.SH NAME
|
|
.LP
|
|
.B swift-ring-builder
|
|
\- Openstack-swift ring builder
|
|
|
|
.SH SYNOPSIS
|
|
.LP
|
|
.B swift-ring-builder
|
|
<builder_file> <commands> <arguments> <...>
|
|
|
|
.SH DESCRIPTION
|
|
.PP
|
|
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-memory 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.
|
|
.PP
|
|
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
|
|
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.
|
|
.PP
|
|
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.
|
|
|
|
|
|
.SH SEARCH
|
|
.PD 0
|
|
|
|
.IP "\fB<search-value>\fR"
|
|
.RS 5
|
|
.IP "Can be of the form:"
|
|
.IP "d<device_id>z<zone>-<ip>:<port>/<device_name>_<meta>"
|
|
|
|
.IP "Any part is optional, but you must include at least one, examples:"
|
|
|
|
.RS 3
|
|
.IP "d74 Matches the device id 74"
|
|
.IP "z1 Matches devices in zone 1"
|
|
.IP "z1-1.2.3.4 Matches devices in zone 1 with the ip 1.2.3.4"
|
|
.IP "1.2.3.4 Matches devices in any zone with the ip 1.2.3.4"
|
|
.IP "z1:5678 Matches devices in zone 1 using port 5678"
|
|
.IP ":5678 Matches devices that use port 5678"
|
|
.IP "/sdb1 Matches devices with the device name sdb1"
|
|
.IP "_shiny Matches devices with shiny in the meta data"
|
|
.IP "_'snet: 5.6.7.8' Matches devices with snet: 5.6.7.8 in the meta data"
|
|
.IP "[::1] Matches devices in any zone with the ip ::1"
|
|
.IP "z1-[::1]:5678 Matches devices in zone 1 with ip ::1 and port 5678"
|
|
.RE
|
|
|
|
Most specific example:
|
|
|
|
.RS 3
|
|
d74z1-1.2.3.4:5678/sdb1_"snet: 5.6.7.8"
|
|
.RE
|
|
|
|
Nerd explanation:
|
|
|
|
.RS 3
|
|
.IP "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."
|
|
.RE
|
|
.RE
|
|
.PD
|
|
|
|
|
|
.SH COMMANDS
|
|
|
|
.PD 0
|
|
|
|
|
|
.IP "\fB<builder_file>\fR"
|
|
.RS 5
|
|
Shows information about the ring and the devices within.
|
|
.RE
|
|
|
|
|
|
.IP "\fBsearch\fR <search-value>"
|
|
.RS 5
|
|
Shows information about matching devices.
|
|
.RE
|
|
|
|
|
|
.IP "\fBadd\fR z<zone>-<ip>:<port>/<device_name>_<meta> <weight>"
|
|
.IP "\fBadd\fR r<region>z<zone>-<ip>:<port>/<device_name>_<meta> <weight>"
|
|
.IP "\fBadd\fR -r <region> -z <zone> -i <ip> -p <port> -d <device_name> -m <meta> -w <weight>"
|
|
.RS 5
|
|
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 multiple device changes and rebalance them all just once.
|
|
.RE
|
|
|
|
|
|
.IP "\fBcreate\fR <part_power> <replicas> <min_part_hours>"
|
|
.RS 5
|
|
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.
|
|
.RE
|
|
|
|
|
|
.IP "\fBlist_parts\fR <search-value> [<search-value>] .."
|
|
.RS 5
|
|
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.
|
|
.RE
|
|
|
|
|
|
.IP "\fBrebalance\fR"
|
|
.RS 5
|
|
Attempts to rebalance the ring by reassigning partitions that haven't been recently reassigned.
|
|
.RE
|
|
|
|
|
|
.IP "\fBremove\fR <search-value> "
|
|
.RS 5
|
|
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 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.
|
|
.RE
|
|
|
|
|
|
.IP "\fBset_info\fR <search-value> <ip>:<port>/<device_name>_<meta>"
|
|
.RS 5
|
|
Resets the device's information. This information isn't used to assign
|
|
partitions, so you can use 'write_ring' 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.
|
|
.RE
|
|
|
|
|
|
.IP "\fBset_min_part_hours\fR <hours>"
|
|
.RS 5
|
|
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.
|
|
.RE
|
|
|
|
|
|
.IP "\fBset_weight\fR <search-value> <weight>"
|
|
.RS 5
|
|
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.
|
|
.RE
|
|
|
|
|
|
.IP "\fBvalidate\fR"
|
|
.RS 5
|
|
Just runs the validation routines on the ring.
|
|
.RE
|
|
|
|
|
|
.IP "\fBwrite_ring\fR"
|
|
.RS 5
|
|
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.
|
|
.RE
|
|
|
|
|
|
\fBQuick list:\fR add create list_parts rebalance remove search set_info
|
|
set_min_part_hours set_weight validate write_ring
|
|
|
|
\fBExit codes:\fR 0 = ring changed, 1 = ring did not change, 2 = error
|
|
.PD
|
|
|
|
|
|
|
|
|
|
.SH DOCUMENTATION
|
|
.LP
|
|
More in depth documentation about the swift ring and also Openstack-Swift as a
|
|
whole can be found at
|
|
.BI http://swift.openstack.org/overview_ring.html,
|
|
.BI http://swift.openstack.org/admin_guide.html#managing-the-rings
|
|
and
|
|
.BI http://swift.openstack.org
|
|
|
|
|