--- name: "ssm" section: "8" platform: "linux" package: "system-storage-manager" version: "0.3-1" release: "Debian 8 (Jessie)" platforms: ["linux"] url: "https://new.carta.tech/ssm" --- # ssm(8) System Storage Manager: a single tool to manage your storage ## NAME ssm - System Storage Manager: a single tool to manage your storage ## SYNOPSIS **ssm** \[**-h**\] \[**--version**\] \[**-v**\] \[**-f**\] \[**-b** BACKEND\] {check,resize,create,list,add,remove,snapshot} ... **ssm** **create** \[**-h**\] \[**-s** SIZE\] \[**-n** NAME\] \[**--fstype** FSTYPE\] \[**-r** LEVEL\] \[**-I** STRIPESIZE\] \[**-i** STRIPES\] \[**-p** POOL\] \[**device** \[**device** ...\]\] \[mount\] **ssm** **list** \[**-h**\] \[{volumes,vol,dev,devices,pool,pools,fs,filesystems,snap,snapshots}\] **ssm** **remove** \[**-h**\] \[**-a**\] \[**items** \[**items** ...\]\] **ssm** **resize** \[**-h**\] \[**-s** SIZE\] **volume** \[**device** \[**device** ...\]\] **ssm** **check** \[**-h**\] **device** \[**device** ...\] **ssm** **snapshot** \[**-h**\] \[**-s** SIZE\] \[**-d** DEST \| **-n** NAME\] volume **ssm** **add** \[**-h**\] \[**-p** POOL\] **device** \[**device** ...\] ## DESCRIPTION System Storage Manager provides easy to use command line interface to manage your storage using various technologies like lvm, btrfs, encrypted volumes and more. In more sophisticated enterprise storage environments, management with Device Mapper (dm), Logical Volume Manager (LVM), or Multiple Devices (md) is becoming increasingly more difficult. With file systems added to the mix, the number of tools needed to configure and manage storage has grown so large that it is simply not user friendly. With so many options for a system administrator to consider, the opportunity for errors and problems is large. The btrfs administration tools have shown us that storage management can be simplified, and we are working to bring that ease of use to Linux filesystems in general. ## OPTIONS - **-h, --help** show this help message and exit - **--version** show program's version number and exit - **-v, --verbose** Show aditional information while executing. - **-f, --force** Force execution in the case where ssm has some doubts or questions. - **-b** *BACKEND,* **--backend** *BACKEND* Choose backend to use. Currently you can choose from (lvm,btrfs). ## SYSTEM STORAGE MANAGER COMMANDS ### Introduction System Storage Manager have several commands you can specify on the command line as a first argument to the ssm. They all have specific use and its own arguments, but global ssm arguments are propagated to all commands. ### Create command **ssm** **create** \[**-h**\] \[**-s** SIZE\] \[**-n** NAME\] \[**--fstype** FSTYPE\] \[**-r** LEVEL\] \[**-I** STRIPESIZE\] \[**-i** STRIPES\] \[**-p** POOL\] \[**device** \[**device** ...\]\] \[mount\] This command creates a new volume with defined parameters. If **device** is provided it will be used to create a volume, hence it will be added into the **pool** prior the volume creation (See *Add command section*). More devices can be used to create a volume. If the **device** is already used in the different pool, then **ssm** will ask you whether you want to remove it from the original pool. If you decline, or the removal fails, then the **volume** creation fails if the *SIZE* was not provided. On the other hand, if the *SIZE* is provided and some devices can not be added to the **pool** the volume creation might succeed if there is enough space in the **pool**. *POOL* name can be specified as well. If the pool exists new volume will be created from that pool (optionally adding **device** into the pool). However if the *POOL* does not exist **ssm** will attempt to create a new pool with provided **device** and then create a new volume from this pool. If **--backend** argument is omitted, the default **ssm** backend will be used. Default backend is *lvm*. **ssm** also supports creating RAID configuration, however some back-ends might not support all the levels, or it might not support RAID at all. In this case, volume creation will fail. If **mount** point is provided **ssm** will attempt to mount the volume after it is created. However it will fail if mountable file system is not present on the volume. - **-h, --help** show this help message and exit - **-s** *SIZE,* **--size** *SIZE* Gives the size to allocate for the new logical volume A size suffix K\|k, M\|m, G\|g, T\|t, P\|p, E\|e can be used to define 'power of two' units. If no unit is provided, it defaults to kilobytes. This is optional if if not given maximum possible size will be used. - **-n** *NAME,* **--name** *NAME* The name for the new logical volume. This is optional and if omitted, name will be generated by the corresponding backend. - **--fstype** *FSTYPE* Gives the file system type to create on the new logical volume. Supported file systems are (ext3, ext4, xfs, btrfs). This is optional and if not given file system will not be created. - **-r** *LEVEL,* **--raid** *LEVEL* Specify a RAID level you want to use when creating a new volume. Note that some backends might not implement all supported RAID levels. This is optional and if no specified, linear volume will be created. You can choose from the following list of supported levels (0,1,10). - **-I** *STRIPESIZE,* **--stripesize** *STRIPESIZE* Gives the number of kilobytes for the granularity of stripes. This is optional and if not given, backend default will be used. Note that you have to specify RAID level as well. - **-i** *STRIPES,* **--stripes** *STRIPES* Gives the number of stripes. This is equal to the number of physical volumes to scatter the logical volume. This is optional and if stripesize is set and multiple devices are provided stripes is determined automatically from the number of devices. Note that you have to specify RAID level as well. - **-p** *POOL,* **--pool** *POOL* Pool to use to create the new volume. ### List command **ssm** **list** \[**-h**\] \[{volumes,vol,dev,devices,pool,pools,fs,filesystems,snap,snapshots}\] List informations about all detected devices, pools, volumes and snapshots found in the system. **list** command can be used either alone to list all the information, or you can request specific section only. Following sections can be specified: - **{volumes \| vol}** List information about all **volumes** found in the system. - **{devices \| dev}** List information about all **devices** found in the system. Some devices are intentionally hidden, like for example cdrom, or DM/MD devices since those are actually listed as volumes. - **{pools \| pool}** List information about all **pools** found in the system. - **{filesystems \| fs}** List information about all volumes containing **filesystems** found in the system. - **{snapshots \| snap}** List information about all **snapshots** found in the system. Note that some back-ends does not support snapshotting and some can not distinguish between snapshot and regular volume. in this case **ssm** will try to recognize volume name in order to identify **snapshot**, but if the **ssm** regular expression does not match the snapshot pattern, this snapshot will not be recognized. - **-h, --help** show this help message and exit ### Remove command **ssm** **remove** \[**-h**\] \[**-a**\] \[**items** \[**items** ...\]\] This command removes **item** from the system. Multiple items can be specified. If the **item** can not be removed for some reason, it will be skipped. **item** can represent: - **device** Remove **device** from the pool. Note that this can not be done in some cases where the device is used by pool. You can use **-f** argument to *force* removal. If the device does not belong to any pool, it will be skipped. - **pool** Remove the **pool** from the system. This will also remove all volumes created from that pool. - **volume** Remove the **volume** from the system. Note that this will fail if the **volume** is mounted and it can not be *forced* with **-f**. - **-h, --help** show this help message and exit - **-a, --all** Remove all pools in the system. ### Resize command **ssm** **resize** \[**-h**\] \[**-s** SIZE\] **volume** \[**device** \[**device** ...\]\] Change size of the **volume** and file system. If there is no file system only the **volume** itself will be resized. You can specify **device** to add into the **volume** pool prior the resize. Note that **device** will only be added into the pool if the **volume** size is going to grow. If the **device** is already used in the different pool, then **ssm** will ask you whether you want to remove it from the original pool. In some cases file system has to be mounted in order to resize. This will be handled by **ssm** automatically by mounting the **volume** temporarily. - **-h, --help** show this help message and exit - **-s** *SIZE,* **--size** *SIZE* New size of the volume. With the + or - sign the value is added to or subtracted from the actual size of the volume and without it, the value will be set as the new volume size. A size suffix of \[k\|K\] for kilobytes, \[m\|M\] for megabytes, \[g\|G\] for gigabytes, \[t\|T\] for terabytes or \[p\|P\] for petabytes is optional. If no unit is provided the default is kilobytes. ### Check command **ssm** **check** \[**-h**\] **device** \[**device** ...\] Check the file system consistency on the **volume**. You can specify multiple volumes to check. If there is no file system on the **volume**, this **volume** will be skipped. In some cases file system has to be mounted in order to check the file system This will be handled by **ssm** automatically by mounting the **volume** temporarily. - **-h, --help** show this help message and exit ### Snapshot command **ssm** **snapshot** \[**-h**\] \[**-s** SIZE\] \[**-d** DEST \| **-n** NAME\] volume Take a snapshot of existing **volume**. This operation will fail if back-end which the **volume** belongs to does not support snapshotting. Note that you can not specify both *NAME* and *DESC* since those options are mutually exclusive. In some cases file system has to be mounted in order to take a snapshot of the **volume**. This will be handled by **ssm** automatically by mounting the **volume** temporarily. - **-h, --help** show this help message and exit - **-s** *SIZE,* **--size** *SIZE* Gives the size to allocate for the new snapshot volume A size suffix K\|k, M\|m, G\|g, T\|t, P\|p, E\|e can be used to define 'power of two' units. If no unit is provided, it defaults to kilobytes. This is option and if not give, the size will be determined automatically. - **-d** *DEST,* **--dest** *DEST* Destination of the snapshot specified with absolute path to be used for the new snapshot. This is optional and if not specified default backend policy will be performed. - **-n** *NAME,* **--name** *NAME* Name of the new snapshot. This is optional and if not specified default backend policy will be performed. ### Add command **ssm** **add** \[**-h**\] \[**-p** POOL\] **device** \[**device** ...\] This command adds **device** into the pool. The **device** will not be added if it's already part of different pool. When multiple devices are provided, all of them are added into the pool. If one of the devices can not be added into the pool for some reason, it will be skipped. If no pool is specified, default pool will be chosen. In the case of non existing pool, it will be created using provided devices. - **-h, --help** show this help message and exit - **-p** *POOL,* **--pool** *POOL* Pool to add device into. If not specified the default pool is used. ## BACK-ENDS ### Introduction Ssm aims to create unified user interface for various technologies like Device Mapper (dm), Btrfs file system, Multiple Devices (md) and possibly more. In order to do so we have a core abstraction layer in **ssmlib/main.py**. This abstraction layer should ideally know nothing about the underlying technology, but rather comply with **device**, **pool** and **volume** abstraction. Various backends can be registered in **ssmlib/main.py** in order to handle specific storage technology implementing methods like *create*, *snapshot*, or *remove* volumes and pools. The core will then call these methods to manage the storage without needing to know what lies underneath it. There are already several backends registered in ssm. ### Btrfs backend Btrfs is the file system with many advanced features including volume management. This is the reason why btrfs is handled differently than other *conventional* file systems in **ssm**. It is used as a volume management back-end. Pools, volumes and snapshots can be created with btrfs backend and here is what it means from the btrfs point of view: - **pool** Pool is actually a btrfs file system itself, because it can be extended by adding more devices, or shrink by removing devices from it. Subvolumes and snapshots can also be created. When the new btrfs pool should be created **ssm** simply creates a btrfs file system, which means that every new btrfs pool has one volume of the same name as the pool itself which can not be removed without removing the entire pool. Default btrfs pool name is **btrfs\_pool**. When creating new btrfs pool, the name of the pool is used as the file system label. If there is already existing btrfs file system in the system without a label, btrfs pool name will be generated for internal use in the following format "btrfs\_{device base name}". Btrfs pool is created when **create** or **add** command is used with devices specified and non existing pool name. - **volume** Volume in btrfs back-end is actually just btrfs subvolume with the exception of the first volume created on btrfs pool creation, which is the file system itself. Subvolumes can only be created on btrfs file system when the it is mounted, but user does not have to worry about that, since **ssm** will automatically mount the file system temporarily in order to create a new subvolume. Volume name is used as subvolume path in the btrfs file system and every object in this path must exists in order to create a volume. Volume name for internal tracking and for representing to the user is generated in the format "{pool\_name}:{volume name}", but volumes can be also referenced with its mount point. Btrfs volumes are only shown in the *list* output, when the file system is mounted, with the exception of the main btrfs volume - the file system itself. New btrfs volume can be created with **create** command. - **snapshot** Btrfs file system support subvolume snapshotting, so you can take a snapshot of any btrfs volume in the system with **ssm**. However btrfs does not distinguish between subvolumes and snapshots, because snapshot actually is just a subvolume with some block shared with different subvolume. It means, that **ssm** is not able to recognize btrfs snapshot directly, but instead it is trying to recognize special name format of the btrfs volume. However, if the *NAME* is specified when creating snapshot which does not match the special pattern, snapshot will not be recognized by the **ssm** and it will be listed as regular btrfs volume. New btrfs snapshot can be created with **snapshot** command. - **device** Btrfs does not require any special device to be created on. ### Lvm backend Pools, volumes and snapshots can be created with lvm, which pretty much match the lvm abstraction. - **pool** Lvm pool is just *volume group* in lvm language. It means that it is grouping devices and new logical volumes can be created out of the lvm pool. Default lvm pool name is **lvm\_pool**. Lvm pool is created when **create** or **add** command is used with devices specified and non existing pool name. - **volume** Lvm volume is just *logical volume* in lvm language. Lvm volume can be created wit **create** command. - **snapshot** Lvm volumes can be snapshotted as well. When a snapshot is created from the lvm volume, new *snapshot* volume is created, which can be handled as any other lvm volume. Unlike *btrfs* lvm is able to distinguish snapshot from regular volume, so there is no need for a snapshot name to match special pattern. - **device** Lvm requires *physical device* to be created on the device, but with **ssm** this is transparent for the user. ### Crypt backend Crypt backend in **ssm** is currently limited to only gather the information about encrypted volumes in the system. You can not create or manage encrypted volumes or pools, but it will be extended in the future. ### MD backend MD backend in **ssm** is currently limited to only gather the information about MD volumes in the system. You can not create or manage MD volumes or pools, but it will be extended in the future. ## EXAMPLES **List** system storage information: ``` # ssm list ``` **List** all pools in the system: ``` # ssm list pools ``` **Create** a new 100GB **volume** with default lvm backend using */dev/sda* and */dev/sdb* with xfs file system: ``` # ssm create --size 100G --fs xfs /dev/sda /dev/sdb ``` **Create** a new **volume** with btrfs backend using */dev/sda* and */dev/sdb* and let the volume to be RAID 1: ``` # ssm -b btrfs create --raid 1 /dev/sda /dev/sdb ``` Using lvm backend **create** a RAID 0 **volume** with devices */dev/sda* and */dev/sdb* with 128kB stripe size, ext4 file system and mount it on */home*: ``` # ssm create --raid 0 --stripesize 128k /dev/sda /dev/sdb /home ``` **Extend** btrfs **volume** *btrfs\_pool* by 500GB and use */dev/sdc* and */dev/sde* to cover the resize: ``` # ssm resize -s +500G btrfs_pool /dev/sdc /dev/sde ``` **Shrink volume** */dev/lvm\_pool/lvol001* by 1TB: ``` # ssm resize -s-1t /dev/lvm_pool/lvol001 ``` **Remove** */dev/sda* **device** from the pool, remove the *btrfs\_pool* **pool** and also remove the **volume** */dev/lvm\_pool/lvol001*: ``` # ssm remove /dev/sda btrfs_pool /dev/lvm_pool/lvol001 ``` **Take a snapshot** of the btrfs volume *btrfs\_pool:my\_volume*: ``` # ssm snapshot btrfs_pool:my_volume ``` **Add devices** */dev/sda* and */dev/sdb* into the *btrfs\_pool* pool: ``` # ssm add -p btrfs_pool /dev/sda /dev/sdb ``` ## ENVIRONMENT VARIABLES - **SSM\_DEFAULT\_BACKEND** Specify which backend will be used by default. This can be overridden by specifying **-b** or **--backend** argument. Currently only *lvm* and *btrfs* is supported. - **SSM\_LVM\_DEFAULT\_POOL** Name of the default lvm pool to be used if **-p** or **--pool** argument is omitted. - **SSM\_BTRFS\_DEFAULT\_POOL** Name of the default btrfs pool to be used if **-p** or **--pool** argument is omitted. ## LICENCE (C)2011 Red Hat, Inc., Lukas Czerner \<*lczerner@redhat.com*\> This program 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, either version 2 of the License, or (at your option) any later version. This program 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 this program. If not, see \<*http://www.gnu.org/licenses/*\>. ## REQUIREMENTS Python 2.6 or higher is required to run this tool. System Storage Manager can only be run as root since most of the commands requires root privileges. There are other requirements listed bellow, but note that you do not necessarily need all dependencies for all backends, however if some of the tools required by the backend is missing, the backend would not work. ### Python modules - • os - • re - • sys - • stat - • argparse - • datetime - • threading - • subprocess ### System tools - • tune2fs - • fsck.SUPPORTED\_FS - • resize2fs - • xfs\_db - • xfs\_check - • xfs\_growfs - • mkfs.SUPPORTED\_FS - • which - • mount - • blkid - • wipefs ### Lvm backend - • lvm2 binaries ### Btrfs backend - • btrfs progs ### Crypt backend - • dmsetup - • cryptsetup ## AVAILABILITY **System storage manager** is available from *http://storagemanager.sourceforge.net*. You can subscribe to *storagemanager-devel@lists.sourceforge.net* to follow the current development. ## AUTHOR Lukáš Czerner \ ## COPYRIGHT 2012, Red Hat, Inc., Lukáš Czerner \