---
name: "swift-ring-builder"
section: "8"
platform: "linux"
package: "swift"
version: "1.4.8-2+deb7u1"
release: "Debian 7 (Wheezy)"
platforms: ["linux"]
url: "https://new.carta.tech/swift-ring-builder/8"
---

# swift-ring-builder(8)

Manipulate the swift ring storage devices.

## NAME

swift-ring-builder - Manipulate the swift ring storage devices.

## SYNOPSIS

**swift-ring-builder** **\<builder\_file\>** **\[ACTION\]** **\[parameters\]**

## DESCRIPTION

**swift-ring-builder**

Manipulate the swift ring. Please contribute a better long description!

## PARAMETERS

The parameter \[ACTION\] can take one of the following values:

**create** **search** **add** **set\_weight** **set\_info** **remove** **rebalance** **validate** **write\_ring** **set\_min\_part\_hours**

If action is not specified, then swift-ring-builder will display all the storage devices. Below is a full description of each individual actions. In each individual action, you may specify a \<search-value\>. In that case, then \<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 part. 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

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.

## CREATE

**swift-ring-builder** **\<builder\_file\>** **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.

## SHOW

**swift-ring-builder** **\<builder\_file\>**

Shows information about the ring and the devices within.

## SEARCH

**swift-ring-builder** **\<builder\_file\>** **search** **\<search-value\>**

Shows information about matching devices.

## ADD

**swift-ring-builder** **\<builder\_file\>** **add** **z\<zone\>-\<ip\>:\<port\>/\<device\_name\>\_\<meta\>** **\<weight\>**

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.

## SET WEIGHT

**swift-ring-builder** **\<builder\_file\>** **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.

## SET INFO

**swift-ring-builder** **\<builder\_file\>** **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 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.

## REMOVE

**swift-ring-builder** **\<builder\_file\>** **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 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.

## REBALANCE

**swift-ring-builder** **\<builder\_file\>** **rebalance**

Attempts to rebalance the ring by reassigning partitions that haven't been recently reassigned.

## VALIDATE

**swift-ring-builder** **\<builder\_file\>** **validate**

Just runs the validation routines on the ring.

## WRITE RING

**swift-ring-builder** **\<builder\_file\>** **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.

## SET MIN PART HOURS

**swift-ring-builder** **\<builder\_file\>** **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.