Ubuntu Manpage: mfsscadmin - MooseFS storage class administration tool

Provided by: moosefs-client_3.0.117-1.1build2_amd64

NAME

       mfsscadmin - MooseFS storage class administration tool

SYNOPSIS

       mfsscadmin  [/MOUNTPOINT]  create|make  [-a admin_only] [-m mode] [-C CREATION_LABELS] -K KEEP_LABELS [-A
       ARCH_LABELS -d ARCH_DELAY] SCLASS_NAME...

       mfsscadmin [/MOUNTPOINT] create|make [-a admin_only] [-m mode] LABELS SCLASS_NAME...

       mfsscadmin  [/MOUNTPOINT]  change|modify  [-f]  [-a  admin_only]  [-m  mode]  [-C  CREATION_LABELS]   [-K
       KEEP_LABELS] [-A ARCH_LABELS] [-d ARCH_DELAY] SCLASS_NAME...

       mfsscadmin [/MOUNTPOINT] delete|remove SCLASS_NAME...

       mfsscadmin [/MOUNTPOINT] copy|duplicate SRC_SCLASS_NAME DST_SCLASS_NAME...

       mfsscadmin [/MOUNTPOINT] rename SRC_SCLASS_NAME DST_SCLASS_NAME

       mfsscadmin [/MOUNTPOINT] list [-l]

DESCRIPTION

       mfsscadmin  is  a  tool  for defining storage classes, which can be later applied to MooseFS objects with
       mfssetsclass, mfsgetsclass etc.  Storage class is a set of labels expressions and options that  indicate,
       on which chunkservers the files in this class should be written and later kept.

COMMANDS

       create|make  creates  a  new  storage class with given options, described below and names it SCLASS_NAME;
       there can be more than one name provided, multiple storage classes  with  the  same  definition  will  be
       created then

       change|modify changes the given options in a class or classes indicated by SCLASS_NAME parameter(s)

       delete|remove  removes  the class or classes indicated by SCLASS_NAME parameter(s); if any of the classes
       is not empty (i.e. it is still used by some MooseFS objects), it will not be removed and  the  tool  will
       return an error and an error message will be printed; empty classes will be removed in any case

       copy|duplicate copies class indicated by SRC_SCLASS_NAME under a new name provided with DST_SCLASS_NAME

       rename changes the name of a class from SRC_SCLASS_NAME to DST_SCLASS_NAME

       list lists all the classes

OPTIONS

       -C  optional  parameter,  that  tells  the  system  to which chunkservers, defined by the CREATION_LABELS
       expression, the chunk should be first written just after creation; if this parameter is not provided  for
       a class, the KEEP_LABELS chunkservers will be used

       -K mandatory parameter (assumed in the second, abbreviated version of the command), that tells the system
       on  which chunkservers, defined by the KEEP_LABELS expression, the chunk(s) should be kept always, except
       for special conditions like creating and archiving, if defined

       -A optional parameter,  that  tells  the  system  on  which  chunkservers,  defined  by  the  ARCH_LABELS
       expression,  the  chunk(s)  should  be kept for archiving purposes; the system starts to treat a chunk as
       archive, when the last modification time of the file it belongs to is  older  than  the  number  of  days
       specified with -d option

       -d  optional  parameter  that  MUST be defined when -A is defined, ARCH_DELAY parameter defines after how
       many days from last modification time a file (and its chunks) are treated as archive

       -a can be either 1 or 0 and indicates if the storage class is available to everyone (0) or admin only (1)

       -f force the changes on a predefined storage class (see below), use with caution!

       -m is described below in CREATION MODES section

       -l list also definitions, not only the names of existing storage classes

LABELS EXPRESSIONS

       Labels are letters (A-Z - 26 letters) that can be assigned to chunkservers.  Each  chunkserver  can  have
       multiple  (up to 26) labels. Labels are defined in mfschunkserver.cfg file, for more information refer to
       the appropriate manpage.

       Labels expression is a set of subexpressions  separated  by  commas,  each  subexpression  specifies  the
       storage  schema  of one copy of a file. Subexpression can be: an asterisk or a label schema. Label schema
       can be one label or an expression with sums, multiplications and brackets. Sum means a file can be stored
       on any chunkserver matching any element of the sum (logical or).  Multiplication  means  a  file  can  be
       stored  only  on  a  chunkserver  matching  all  elements (logical and).  Asterisk means any chunkserver.
       Identical subexpressions can be shortened by adding a number in front of one instead of  repeating  it  a
       number of times.

       Examples of labels expressions:

       A,B  -  files  will have two copies, one copy will be stored on chunkserver(s) with label A, the other on
       chunkserver(s) with label B

       A,* - files will have two copies, one copy will be stored on chunkserver(s) with label A,  the  other  on
       any chunkserver(s)

       *,* - files will have two copies, stored on any chunkservers (different for each copy)

       AB,C+D - files will have two copies, one copy will be stored on any chunkserver(s) that has both labels A
       and  B  (multiplication  of labels), the other on any chunkserver(s) that has either the C label or the D
       label (sum of labels)

       A,B[X+Y],C[X+Y] - files will have three copies, one copy will be stored  on  any  chunkserver(s)  with  A
       label,  the  second  on  any chunserver(s) that has the B label and either X or Y label, the third on any
       chunkserver(s), that has the C label and either X or Y label

       A,A expression is equivalent to 2A expression

       A,BC,BC,BC expression is equivalent to A,3BC expression

       *,* expression is equivalent to 2* expression is equivalent to 2 expression

MODES

It is important to specify what to do when it is not possible to meet the labels requirement of a storage
class, i.e.: there is no space available on all servers with needed labels, there is not enough servers
with needed labels or servers with needed labels are all busy. The question is if the system should
create chunks on other servers (with non-matching labels) or not. This decision must be made by the user
and hence the -m option.

In DEFAULT mode (no option or option -m D) in case of overloaded servers the system will wait for them,
but in case of no space available it will use other servers and will replicate data to correct servers
when it becomes possible. This means if some servers are in busy state for a long time, it might not be
possible to create new chunks with certain storage classes and endangered (undergoal) chunks from those
classes are at higher risk of being completely lost due to delayed replications.

Option -m S turns on STRICT mode. In this mode, during writing a new file, the system will return error
(ENOSPC) in case of no space available on servers marked with labels specified for chunk creation. It
will still wait for overloaded servers. Undergoal repliactions will not be performed if there is no space
on servers with labels matching the storage class. This means high risk of losing data if servers with
some labels are permamently filled up with data!

Option -m L turns on LOOSE mode. In this mode the system will immediately use other servers in case of
overloaded servers or no space on servers and will replicate data to correct servers when it becomes
possible. There is no delay or error on file creation and undergoal replications are always done as soon
as possible.

This table sums up the modes:
DEFAULT STRICT LOOSE
CREATE - BUSY WAIT WAIT WRITE ANY
CREATE - NO SPACE WRITE ANY ENOSPC WRITE ANY
REPLICATE - BUSY WAIT WAIT WRITE ANY
REPLICATE - NO SPACE WRITE ANY NO COPY WRITE ANY

PREDEFINED STORAGE CLASSES

       For  compatibility  reasons, every fresh or freshly upgraded instance of MooseFS has 9 predefined storage
       classes. Their names are single digits, from 1 to 9,  and  their  definitions  are  *  to  9*.  They  are
       equivalents  of  simple  numeric  goals  from previous versions of the system. In case of an upgrade, all
       files that had goal N before upgrade, will now have N storage class.  These classes can be modified  only
       when  option  -f  is  specified.  It  is  advised to create new storage classes in an upgraded system and
       migrate files with mfsxchgsclass tool, rather than modify the predefined classes. The predefined  classes
       CANNOT be deleted nor renamed.

REPORTING BUGS

       Report bugs to <bugs@moosefs.com>.

COPYRIGHT

       Copyright (C) 2023 Jakub Kruszona-Zawadzki, Saglabs SA

       This file is part of MooseFS.

       MooseFS  is  free  software;  you can redistribute it and/or modify it under the terms of the GNU General
       Public License as published by the Free Software Foundation, version 2 (only).

       MooseFS is distributed in the hope that it will be useful, but WITHOUT ANY  WARRANTY;  without  even  the
       implied  warranty  of  MERCHANTABILITY  or  FITNESS  FOR A PARTICULAR PURPOSE. See the GNU General Public
       License for more details.

       You should have received a copy of the GNU General Public License along with MooseFS; if  not,  write  to
       the  Free  Software  Foundation,  Inc.,  51 Franklin St, Fifth Floor, Boston, MA 02111-1301, USA or visit
       http://www.gnu.org/licenses/gpl-2.0.html