Ubuntu Manpage: mfsscadmin - MooseFS storage class administration tool

Provided by: moosefs-client_3.0.117-1_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