QBMANAGE

Section: Maintenance Commands (8)
Updated: June 2019

NAME

qbmanage – Qos Bandwidth Management Utility

SYNOPSIS

qbmanage –help [–command] [–verbose]
qbmanage –new –fsname|-f FsName [–on=[true|false|1|0]] [–mover=[true|false|1|0]] [–all_sg=[true|1] –sgcapacity amount] [–all_sg=[false|0]] [–sgcapacity amount] [–activate when] [–min_change amount] [–min_alloc amount] [–reserved_fc amount] [–reserved_fs amount] [–reserved_low amount] [–reserved_mover amount] [–class fair_share|first_come|low_share|] [–min_bw amount] [–max_bw amount] [–nofsm] common_options
qbmanage –modify –fsname|-f FsName [–on=[true|false|1|0]] [–mover=[true|false|1|0]] [–all_sg=[true|1] –sgcapacity amount] [–all_sg=[false|0]] [–activate when] [–min_change amount] [–min_alloc amount] [–sgcapacity amount] [–reserved_fc amount] [–reserved_fs amount] [–reserved_low amount] [–reserved_mover amount] [–class fair_share|first_come|low_share|] [–min_bw amount] [–max_bw amount] [–timeout seconds] [–nofsm] common_options
qbmanage –addsg –fsname|-f FsName –sgname SgName | ‘#SgIndex’ [–sgcapacity amount] [–reserved_fc amount] [–reserved_fs amount] [–reserved_low amount] [–reserved_mover amount] [–class fair_share|first_come|low_share|] [–min_bw amount] [–max_bw amount] [–nofsm] common_options
qbmanage –addclient –fsname|-f FsName –clientname IpAddress [–sgname|-g SgName | ‘#SgIndex’] [–class fair_share|first_come|low_share|] [–min_bw amount] [–max_bw amount] [–nofsm] common_options
qbmanage –rmsg –fsname|-f FsName –sgname SgName | ‘#SgIndex’ [–nofsm] common_options
qbmanage –rmclient –fsname|-f FsName –clientname IpAddress –sgname SgName | ‘#SgIndex’ [–nofsm] common_options
qbmanage –delete –fsname|-f FsName [–nofsm] common_options
qbmanage –start –fsname|-f FsName [–timeout seconds] common_options
qbmanage –reread –fsname|-f FsName [–timeout seconds] common_options
qbmanage –newconfig –fsname|-f FsName [–timeout seconds] common_options
qbmanage –putconfig –fsname|-f FsName [–configfile filename] [–timeout seconds] common_options
qbmanage –getconfig –fsname|-f FsName [–configfile filename] [–timeout seconds] common_options
qbmanage –status –fsname|-f FsName [–timeout seconds] common_options
qbmanage –validate –fsname|-f FsName [–print] [–configfile filename] [–nofsm] common_options

DESCRIPTION

qbmanage is used to manage the QOS bandwidth management(QBM) configurationfor file systems. QOS bandwidth management supports StorNext 6 SAN and LAN clients. The mover capability of QBM requires StorNext 6.2 (or newer) on all StorNext clients mounting the file system. qbmanage can be used to create or remove a configuration file, modify the general parameters, add and remove stripe groups, add and remove clients, and validate and print the configuration file. The configuration file has sections for general parameters, stripe group parameters and client parameters. See the qbm.conf manpage for more information. Creation or modification of the QBM configuration file requires restarting the file system or use of the –newconfig option.

Three classes are defined, with different behaviors. Each client mounting the file system is assigned to a class which determines the bandwidth allocation behavior. The classes are called first_come, fair_share and low_share. Each has a priority with first_come being the highest priority followed by fair_share and then low_share.

Alternatively, a mover configuration can be defined for throttling storage manager Distributed Data Movers (DDM). Other clients are not throttled and must not be configured.

The utility can also be used to signal the fsm to start QBM, to read the current QBM configuration file, to retrieve the configuration file or to replace the configuration file. The start command is available when the initial configuration file has the on option set to false. To use these commands, a QBM configuration file must exist in the config directory before the related file system is started. The start command is only available when the initial configuration file has the “on” option set to false.

When running this command on an HA pair, the putconfig command can only be run if the fsm is running on the primary node. The start, newconfig, getconfig and status can be run from both nodes of the HA pair. The validate command can be run on either node of an HA pair. All other commands must be run on the primary node of an HA pair, regardless of where the fsm is running. The configuration file must always be updated on the primary node of an HA pair.

If any of the following keywords, reserved_fc, reserved_fs, reserved_low, reserved_mover, are specified for a stripe group, the general reserved values will not be used for any of the reserved settings. If either the minimum bandwidth or the maximum bandwidth is specified for a stripe group or client, both of the values are considered specified. If the minimum bandwidth is specified without the maximum bandwidth, the maximum bandwidth is set equal to the minimum bandwidth. If the maximum bandwidth is specified without the minimum bandwidth, the minimum bandwidth is set to the default minimum bandwidth of 1048576.

OPTIONS

Options that start with can be abbreviated to just their unique prefix; however when called from scripts the full option name should be used to avoid future abbreviation conflicts if new options are added.

Numerical values can be specified or displayed using suffixes. Prior to 6.3, if K, M, or G was appended to the value, then the value was in multiples of 1024, 1048576 or 1073741824. Now suffixes specified as K, M, G or KB, MB, GB are in thousands, millions and billions. Suffixes specified as KiB, MiB, GiB are multiples of 1024, 1048576 or 1073741824. When displaying numerical values, if the value is evenly divisible by 1024, then suffixes of KiB, MiB and GiB are used. Setting the environment variable QBM_OLD_KMG forces the old behavior.

For options that begin with — and have optional arguments, the argument must be preceded by an equal sign. Options that have required arguments can have the argument separated by either a space or an equal sign, e.g.

–fsname FsName
–fsname=FsName

are equivalent.

–fsname|-f FsName
Selects a given file system. If the file system is not running in the default cluster or administrative domain, those may added to the file system name using the syntax:

FsName[@cluster[/addom]]
–sgname|-g SgName | ‘#SgIndex’
Selects a given stripe group by name or index. The hash sign, which is part of the index syntax, must be escaped to avoid special processing by the shell.
–new
Creates a QBM configuration file with the specified general parameters. The file system must be restarted to activate the new configuration file. If it replaces an existing configuration, the –newconfig option may be used for activation.
–modify
Modifies the general parameters of an existing QBM configuration file.
–addsg
Adds a stripe group to an existing QBM configuration file.
–rmsg
Removes a stripe group from an existing QBM configuration file.
–addclient
Adds a client to an existing QBM configuration file.
–rmclient
Removes a client from an existing QBM configuration file.
–delete
Removes an existing QBM configuration file.
–start
Activates an existing QBM configuration file that specified the –on option as false. This is used to signal a file system to activate the configuration file that existed when the file system was started.
–newconfig
Activates the current QBM configuration file. This is used to replace the configuration being used by the file system.
–reread
Deprecated option which is the same as –newconfig.
–getconfig
Retrieve the active QBM configuration file from the file system. This requires that the file system be mounted on the system running the command. If no active configuration exists, nothing is returned. The default is to write to stdout.
–putconfig
Sends the specified QBM configuration file to the running file system to replace the configuration being used by the file system.
–status
Retrieve the QBM bandwidth information from the running file system and display the information.
–validate
Validate the current QBM configuration file.
–on=[true|false|1|0]
Change the initial state when the filesystem is started. If the argument is true, bandwidth management is immediately started. If false, the qbmanage must be used to initiate bandwidth management. If the argument is not specified, it defaults to true.
–mover=[true|false|1|0]
Specify the mover implementation of bandwidth management. Only configured clients have their bandwidth managed. Non-regulated clients report bandwidth usage which is used to manage the configured clients. If the argument is not specified, it defaults to false.
–class first_comd|fair_share|low_share|””
Specify the name of the class to be used for the file system(general section), stripe group or client when used with the –new, –addsg, –addclient commands respectively. If mover is configured, no classes can be used. The class is assigned to a client by checking the client configuration, stripe group configuration and file system configuration in that order. If no class is found then the default value of low_share is assgined.
The first_come class has priority over all other classes. A client in this class that is granted bandwidth is guaranteed to retain its minimum bandwidth.
The fair_share class is second in priority for obtaining bandwidth. QBM shares allocation across clients in proportion to their configuration.
The low_share class is third in priority for obtaining bandwidth. QBM shares allocation across clients in proportion to their configuration. Unconfigured clients are assigned to this class by default.
–all_sg=[true|false|1|0]
Specify whether all data stripe groups will have their bandwidth managed. If the argument is true, bandwidth management is implemented on all data stripe groups. A bandwidth capacity is required for bandwidth managed stripe groups, thus –sgcapacity must also be specified with this option. If no configuration exists for a given stripe group, the –sgcapacity value specified as a general parameter will be used. If the argument is not specified, it defaults to false.
–min_change min_change
Set the value used as the minimum amount of change reported to a client. For example, a minimum change of 128KiB would not change the allocated bandwidth for a client if the change would be less than 128KiB difference from the previous value. If the argument is not specified it defaults to 32768.
–min_alloc min_alloc
Sets the lowest bandwidth allocation for a client, which is the initial allocation for unconfigured clients. Specifying a large value combined with a large number of clients can lead to oversubscription. If the argument is not specified, it defaults to 32768. The minimum value is 32768. The maximum value is 1048576.
NOTE: Not intended for general use. Only use when recommended by Quantum Support.
–sgcapacity sgcapacity
Set the default stripe group bandwidth capacity. If no specific configuration of bandwidth capacity is specified for a stripe group, this value will be used. This applies if –all_sg is set, or if a stripe group is configured without a capacity specified. This option is required with the use of –all_sg. If not specified for –add_sg, the value specified in the general options is the default. If there is no value specified in the general options, there is no default. The minimum value is 104857600.
–reserved_fc reserved_fc
Set the default stripe group reserved value for bandwidth for the first come class. If no specific configuration of reserved first come bandwidth is specified for a stripe group, this value will be used. This value applies if –all_sg is set, or if a stripe group is configured without a reserved_fc value specified. If not specified for –add_sg, the value specified in the general options is the default. If there is no value specified in the general options, the default is 0.
–reserved_fs reserved_fs
Set the default stripe group reserved value for bandwidth for the fair share class. If no specific configuration of reserved fair share bandwidth is specified for a stripe group, this value will be used. This value applies if –all_sg is set, or if a stripe group is configured without a reserved_fs value specified. If not specified for –add_sg, the value specified in the general options is the default. If there is no value specified in the general options, the default is 0.
–reserved_low reserved_low
Set the default stripe group reserved value for bandwidth for the low class. If no specific configuration of reserved low bandwidth is specified for a stripe group, this value will be used. This value applies if –all_sg is set, or if a stripe group is configured without a reserved_low value specified. If not specified for –add_sg, the value specified in the general options is the default. If there is no value specified in the general options, the default is 0.
–reserved_mover reserved_mover
Set the default stripe group reserved value for bandwidth for the mover class. If no specific configuration of reserved mover bandwidth is specified for a stripe group, this value will be used. This value applies if –all_sg is set, or if a stripe group is configured without a reserved_mover value specified. If not specified for –add_sg, the value specified in the general options is the default. If there is no value specified in the general options, the default is 0.
–min_bw min_bw
Set the default minimum bandwidth given to a client. If specified for the –addclient command, this value is used. If specified for the –addsg command, the value is used for a client which has no specific value. If specified for the –new or –modify commands, the value is used only when there is no specific client value and no specific stripe group value. It is recommended that both –min_bw and –max_bw are explicitly specified together. Failing to do so results in the default value being used. The minimum value and default value is 1048576.
–max_bw max_bw
Set the default maximum bandwidth given to a client. If specified for the –addclient command, this value is used. If specified for the –addsg command, the value is used for a client which has no specific value. If specified for the –new or –modify commands, the value is used only when there is no specific client value and no specific stripe group value. The minimum value and default is 1048576, but will not be less than the minimum bandwidth. It is recommended that both –min_bw and –max_bw are explicitly specified together. Failing to do so results in the default value being used. The minimum value and default value is 1048576.
–activate activate
Specify the action a client must take to initiate bandwidth allocation. If “mount” is specified, the client will be allocated bandwidth at mount time. If “io” is specified, a minimum amount of bandwidth is allocated at mount time, and the first I/O request above the minimum will initiate bandwidth allocation for this client. The default value is io.
–print
Prints the contents of the configuration file with validation.
–configfile
Specifies the name of the configuration file. When retrieving the configuration file, it specifies the file name for the output. When replacing the configuration file, it specifies the input file name.
–nofsm
Not recommended. Allows command not requiring an active fsm to run without the fsm, which prevents some validation. Some commands require the file system be running to execute the command, and don’t support this option.
–timeout seconds
Set the amount of time to wait for the FSM to respond to a query. This value can also be specified in snfs_rest_config.json for all instances of this command. The default is 10 seconds.
–verbose
Verbose mode. It is used with the -h help option.
–yes|-y
Executes command without operator intervention.

EXAMPLES

Create a Qos bandwidth management configuration file with the general parameters set to default values except the all_sg parameter, which is set to true.

rock # qbmanage --new --fsname snfs1 --all_sg --sgcapacity 1G


Add stripe group sg1 to the configuration of file system snfs1 with a bandwidth capacity of 500 MB/sec.

rock # qbmanage --addsg --fsname snfs1 --sgname sg1 --sgcapacity 500M


Add client 190.160.25.100 to the configuration of file system snfs1 for stripe group sg1.

rock # qbmanage --addclient --clientname 190.160.25.100 -f snfs1 --sgname sg1 --min_bw 200M --max_bw 300M


Get Qos bandwidth management configuration for file system snfs1.

rock # qbmanage --getconfig -f snfs1 --configfile current_file


Update Qos bandwidth management configuration for file system snfs1.

rock # qbmanage --putconfig -f snfs1  --configfile new_file


Validate and print the QBM configuration file.

rock # qbmanage --validate -f snfs1  --print


SEE ALSO

cvadmin(8), qbm.conf(5), snfs_rest_config.json(4)