SGMANAGE

Section: Maintenance Commands (8)
Updated: April 2019

NAME

sgmanage – Stripe Group Management Utility

SYNOPSIS

sgmanage command [–sgname|-g SgName | ‘#SgIndex’] [–fsname|-f FsName] [–yes|-y] [–verbose] [–debug|-D] [–help] [–timeout seconds]
sgmanage –list|-l common_options
sgmanage –list_files [–list_output <list_file_path>] common_options
sgmanage –suspend|-s common_options
sgmanage –resume|-r common_options
sgmanage –delete|-d common_options
sgmanage –trim common_options
sgmanage –multipath|-m method common_options
sgmanage –offload
sgoffload
sgmanage –defrag
sgdefrag
sgmanage –add
sgadd
sgmanage –resize
sgresize

DESCRIPTION

sgmanage and related stripe group management utilities allowan administrator to preform various tasks related to stripe groups while the file system is active and in use by clients and their applications. See the snfs_config(5) man page for the definition of a stripe group.

In its basic form, sgmanage can be used to list information about existing stripe groups in a StorNext File System. If no file system name is given, the utility lists the information for all the file systems it can see. The utility can also be used to control the allocation state of a stripe group by enabling or disabling space allocation. In addition, the multipath method of the stripe group may be modified. When using thin-provisioned storage, the size of the LUNS in a stripe group may be increased. Finally, a stripe group can be deleted, which makes it vacant and available for re-use. This can be especially useful for file systems which have stripe groups that have been downed. Prior to StorNext 6.0, this was the only way to retire obsolete storage. The downed stripe group must be empty.

The use of sgmanage requires that the file system be active on the primary node of an HA pair, if HA is configured. If it is active on the secondary, cvadmin subcommand fail can be used to switch it to the primary.

The offload, defrag and delete functions require that the global configuration variable metadataArchive be set to true. If this change needs to be made, the file system must be stopped and restarted for the change to take effect. Wait for the metadata archive database rebuild to complete by monitoring the status with the cvadmin subcommand mdarchive status.

See sgoffload(8) for usage of sgmanage –offload.
See sgdefrag(8) for usage of sgmanage –defrag.
See sgadd(8) for usage of sgmanage –add.
See sgresize(8) for usage of sgmanage –resize.

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.

Options that start with — and take an argument 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 file system name using the syntax:

FsName[@cluster[/addom]]
–sgname|-g SgName | ‘#SgIndex’
Selects a 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.
–multipath|-m method
Change the multipath method of the stripe group. Method can be rotate, static, sticky, balance or cycle.StorNext has the capability of utilizing multiple paths from a system to the SAN disks.

This capability is referred to as “multi-pathing”, or sometimes “multi-HBA support”. (HBA := Host Based Adaptor).

At “disk discovery” time, for each physical path (HBA), a scan of all of the SAN disks visible to that path is initiated, accumulating information such as the SNFS label, and where possible, the disk (or LUN) serial number.

At mount time, the visible set of StorNext labeled disks is matched against the requested disks for the file system to be mounted.

If the requested disk label appears more than once, then a “multi-path” table entry is built for each available path.

If the disk (or LUN) device is capable of returning a serial number, then that serial number is used to further verify that all of the paths to that StorNext labeled device share the same serial number.

If the disk (or LUN) device is not capable of returning a serial number then the device will be used, but StorNext will not be able to discern the difference between a multi-path accessible device, and two or more unique devices that have been assigned duplicate StorNext labels.

The presence of serial numbers can be validated by using the “cvlabel -ls” command. The “-s” option requests the displaying of the serial number along with the normal label information.

There are five modes of multi-path usage which can also be specified in the filesystem config file. In cases where there are multiple paths and an error has been detected, the algorithm falls back to the rotate method. The balance and cycle methods will provide the best aggregate throughput for a cluster of hosts sharing storage.

balance
The balance mode provides load balancing across all the available, active, paths to a device. At I/O submission time, the least used HBA/controller port combination is used as the preferred path. All StorNext File System I/O in progress at the time is taken into account.
cycle
The cycle mode rotates I/O to a LUN across all the available, active, paths to it. As each new I/O is submitted, the next path is selected.
rotate
The rotate mode is the default for configurations where the operating system presents multiple paths to a device.In this mode, as an I/O is initiated, an HBA controller pair to use for this I/O is selected based on a load balance method calculation.

If an I/O terminates in error, a “time penalty” is assessed against that path, and another “Active” path is used. If there are not any “Active” paths that are not already in the “error penalty” state, then a search for an available “Passive” path will occur, possibly triggering an Automatic Volume Transfer to occur in the Raid Controller.

static
The “default” mode for all disks other than Dual Raid controller configurations that are operating in Active/Active mode with AVT enabled.
As disks (or LUNs) are recognized at mount time, they are statically associated with an HBA in rotation.i.e.   given 2 HBA’s, and for disks/LUNs:

                    disk 0 -> HBA 0
                    disk 1 -> HBA 1
                    disk 2 -> HBA 0
                    disk 3 -> HBA 1

                    and so on...

sticky
In this mode, the path to use for an I/O is based on the identity of the target file. This mode will better utilize the controller cache, but will not take advantage of multiple paths for a single file.
The current mode employed by a stripe group can be viewed via the “cvadmin” command “show long”.Permanent modifications may be made by incorporating a “MultiPathMethod” configuration statement in the configuration file for a stripe group.

In the case of an I/O error, that HBA is assessed an “error penalty”, and will not be used for a period of time, after which another attempt to use it will occur.

The first “hard” failure of an HBA often results in a fairly long time-out period (anywhere from 30 seconds to a couple of minutes).

With most HBA’s, once a “hard” failure (e.g. unplugged cable) has been recognized, the HBA immediately returns failure status without a time-out, minimizing the impact of attempting to re-use the HBA periodically after a failure. If the link is restored, most HBA’s will return to operational state on the next I/O request.

–list|-l
List the stripe group information including status and disk nodes in the stripe group. If the –fsname option in not present, it will list the information for all stripe groups in all file systems. Information for a specific stripe group is displayed if –sgname is given. If the –verbose is also selected, a longer version of stats is displayed.
–list_files
List the file paths of files which have at least one extent on the selected stripe group. Information is written to standard output, unless the –list_output option is specified.
–list_output <list_file_path>
Used with –list_files, specifies the file which will contain the list of file paths.
–suspend|–stop|-s
Suspend any new space allocations on a given data stripe group. The –fsname FsName and –sgname SgName | ‘#SgIndex’ options must be included. While writes will be allocated on other data stripe groups, reads can continue on the select stripe group. If there are no other data stripe groups then ENOSPC (no space) is returned. In-use space will reflect the loss of allocatable blocks from the selected stripe group.
–resume|-r
Resume new space allocations on a given data stripe group. The –fsname FsName and –sgname SgName | ‘#SgIndex’ options must be included. Writes will now be allocated on the selected data stripe group. In-use percentage of space now is decreased as blocks are made available for allocation.
–delete|-d
Delete a data stripe group. This can only be done if there is no user data on the stripe group. For a user data only stripe group, the disk luns are actually removed from the configuration and the stripe group is marked VACANT. For a shared metadata/user data stripe group, the stripe group is marked EXCLUSIVE and can used only for metadata allocation. File system clients prior to StorNext 5.4.0 should un-mount the file system prior to the delete and re-mount after.
–trim
This option is for use with thin provisioned devices in the given file system. It causes UNMAPS or TRIM operations for all free space in the given stripe group. This performs the same operations as the cvfsck -U operation, except that with sgmanage, the file system stays on line. During the trim operation, allocations to the given stripe group are suspended, so another data stripe group must be available for file system operations to continue. This option currently only works with Quantum QXS series storage.
–verbose
Verbose mode. More stats are displayed when used with the -l list option. Additional debugging information is also displayed on most commands.
–yes|-y
Executes command without operator intervention.
–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 value is 60 seconds, as specified in the installed file snfs_rest_config.json.

EXAMPLES

List state of all file systems stripe groups

rock # sgmanage --list


List state and information for all stripe groups in file system snfs1.

rock # sgmanage --list -f snfs1


Suspend allocation on stripe group sg1, file system snfs1.

rock # sgmanage --suspend -f snfs1 -g sg1


Resume allocation on stripe group 1, file system snfs1.

rock # sgmanage --resume -f snfs1 -g sg1


NOTE: The sgmanage command is not available on Debian and Ubuntu clients.

SEE ALSO

cvadmin(8), snfs_config(5), sgadd(8), sgdefrag(8), sgoffload(8), sgresize(8), snfs_rest_config.json(4)