Section: Maintenance Commands (8)
Updated: April 2019


sgdefrag – Defrag the free space in a Stripe Group


sgdefrag –fsname|-f FsName [–sgname|-g SgName | ‘#SgIndex’] [–alloc_at_end[=true|false|1|0] [–blocks nblocks] [–keep] [–ignore_affinity] [–minspace|-M] [–yes|-y] [–verbose] [–debug|-D] [–progress ProgressFilePath] [–no_admin_lock] [–timeout seconds] [–otime <[yyyy-mm-dd:]hh:mm:ss>] [–list_frag_count] [–help]
sgmanage –defrag


sgdefrag reduces the amount of free space fragmentation in astripe group through a process called defragmentation. For each file that contains extents on the stripe group, the list of all extents for that file on this stripe group is retrieved from the metadata archive database. These extents are then re-allocated in the file system across all stripe groups or on the same stripe group (see the –keep option).

When re-allocating space, the new blocks are by default allocated at the end of a stripe group. This behavior can be changed to use the allocater’s default algorithms for extent placement. This may be at the start of the stripe group but can be influenced by other factors such as best fit or allocation session reservation. If the only available space is at the end of the stripe group, the allocator will place the new extents here. The placement of file extents affects the performance of writes and reads on traditional spinning disks. Since the speed of the disk is greater on the outside tracks, writes and reads to and from blocks allocated here will outperform writes and reads to and from blocks on the innermost tracks. In some cases, it may be useful to use sgdefrag to free up higher performance blocks taken by older files and leave the new free space available for newly created files. There is no performance difference when a Solid State Device (SSD) is used to hold file data on a stripe group.

Defragging creates fewer larger blocks of free space and often results in fewer larger data extents on the files it operates on. This generally results in better performance for the file system. See also the snfsdefrag(1) command which defrags files instead of stripe groups. Also see the cvfsck(8) command for information regarding the current state of free space fragmentation in a stripe group.

The use of sgdefrag 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 use of sgdefrag also requires 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.

Sgdefrag will also attempt to defrag files as well as free space by combining adjacent source extents from a file on the source stripe group into a single allocation request on the target. This behavior is the default, but will not be used if the minspace option is used. In that case, each source extent will result in a separate call to the allocator. Note also that when snfsdefrag(1) is used to defragment files, it will consolidate all contiguous source extents from all stripe groups.

Sgdefrag makes use of the adminstrative lock feature of StorNext which allows it to move files that are currently open from a client node. It does this by revoking the I/O token from that client. During the time the token is revoked, I/O operations are suspended on that file. This behavior can be overridden with the –no_admin_lock option. Some clients may not support the I/O token operation if the software version is older. In this case, the file is seen to be busy by sgdefrag and the file is skipped. To completely defrag a stripe group, sgdefrag may have to be invoked repeatedly to move the once busy files.

Multiple sgdefrag commands may be invoked simultaneously as long as the source stripe group is not the same.

The sgdefrag(8) command may also be invoked as:

sgmanage –defrag


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

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:

–sgname|-g SgName | ‘#SgIndex’
Name or index of the stripegroup to defragment. The hash sign, which is part of the index syntax, must be escaped to avoid special processing by the shell.
–alloc_at_end[= true | false | 1 | 0]
Specify if new allocations are to be made at the end of the stripe group. The default is that new allocations are made at the end of the stripe group. If specified alone, the value of true is used.
–blocks nblocks
Specify the number of blocks to move. If nblocks is 0, 1/2 of the used blocks will be moved, which is the default behavior. If nblocks is -1, all used blocks will be moved. Otherwise, nblocks will be moved.
Keep the allocations on the same stripe group.
Ignore affinities and allow data to be allocated anywhere. The –keep and –ignore_affinity options are mutually exclusive.
Allocate the smallest possible pieces.
Run the command without prompting for confirmation before making the change.
Show additional output.
Turn on debugging code
–progress ProgressFilePath
Create and periodically update this file with information about how far along we are and how much time remains. This file is in JSON format. Progress information is also written to standard output in normal (not JSON) format.
Do not attempt to temporarily stop I/O related operations on an open file by setting the administrative lock on a file. The default behavior is to attempt to set the administrative lock on each file that is being defragged. If sgdefrag successfully sets the administrative lock, I/O related operations will be suspended for any application that has the file open during the time sgdefrag is operating on that file. If a file is open and the administrative lock cannot be obtained, that file will be skipped.
–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 using the process name entry sgmanage in snfs_rest_config.json. This file is installed by default and has a value of 60 seconds.
–otime [yyyy-mm-dd:]hh:mm:ss
Only operate on files that are older than the specified time, as observed in the atime or mtime field for the file. Note here that it is possible for a client to modify the updating of the atime for a file using mount options noatime or atimedelay. This could cause a file to be defragged even if it has been recently accessed.
List the free space fragment count only, do not attempt the defrag operation.
Print a usage statement.

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



sgadd(8), sgmanage(8), sgoffload(8), sgresize(8), cvadmin(8), cvfsck(8), snfsdefrag(1), snfs_config(5), mount_cvfs(8), snfs_rest_config.json(4)