Go to main content

man pages section 1: User Commands

Exit Print View

Updated: Wednesday, February 10, 2021

swift-ring-builder (1)


swift-ring-builder - OpenStack Swift ring builder


swift-ring-builder <builder_file> <commands> <arguments> <...>


swift-ring-builder(1)           OpenStack Swift          swift-ring-builder(1)

       swift-ring-builder - OpenStack Swift ring builder

       swift-ring-builder <builder_file> <commands> <arguments> <...>

       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.

            Can be of the form:

            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-       Matches devices in zone 1 with the ip
                Matches  devices  in  any  zone  with  the ip
               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:' Matches devices with snet: in the meta
               [::1]            Matches devices in any zone with the ip ::1
               z1-[::1]:5678    Matches devices in zone 1 with ip ::1 and port

            Most specific example:


            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.

            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

            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:" 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.

            Just runs the validation routines on the 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

       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

       See attributes(7) for descriptions of the following attributes:

       |Availability   | cloud/openstack/swift |
       |Stability      | Uncommitted           |
       This    software    was    built    from    source     available     at
       https://github.com/oracle/solaris-userland.    The  original  community
       source      was      downloaded      from        https://tarballs.open-

       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)