1. Manuals
  2. Tumbleweed
  3. barrel
  4. barrel(8)

Scroll to navigation

BARREL(8) Storage Management BARREL(8)

NAME

barrel - Command-line program for storage management

SYNOPSIS

barrel [--global-opts] command [--command-opts] [block-devices]

barrel [--global-opts]

DESCRIPTION

Barrel is a command-line program for storage management. It can work with file systems, LUKS, RAIDs and LVM. The main feature of barrel is to combine the various tools needed to manage the different storage systems in one tool. E.g. with a single command of barrel it is possible to create partitions on several disks, create a RAID from those partitions and create a file system on the RAID.

Barrel probes the complete storage system at startup and does not save the state between invocations. That allows to mix barrel with other storage tools, although in general not concurrently.

CONCEPTS

Script and Interactive Mode

Barrel can run either in script or interactive mode. In script mode the command must be provided on the command line. If no command is provided on the command line the interactive mode is started where a prompt asks for the commands.

Pool

Pools are a set of devices and allow barrel to find suitable disk space on its own. For example when the system has several SSDs and the user wants to create a file system on some SSD barrel can pick an SSD with enough space automatically.

So far devices in a pool must have a partition table to be usable.

Stack

Barrel has a stack that allows commands to be chained. For example creating a RAID places the resulting RAID on the stack. A consecutive command to create a file system can then pick the RAID from the stack. Using the stack the user does not have to deal with the name of the newly created RAID and thus the two commands can be provided on the command line.

The stack can hold different objects: storage objects (e.g. block devices, LVM volume groups or file systems), a mark and arrays. Arrays are constructed using the [ and ] commands.

Devicegraph

Barrel saves all information about storage devices and file systems together with their relations in a devicegraph. At startup the system is probed and the state is saved in the "probed" and the "staging" devicegraphs. All commands, except of the commit command, only modify the staging devicegraph.

Barrel makes a backup of the staging devicegraph whenever it is modified. The last backup can be restored with the command undo.

During commit barrel runs actions to make the system match the staging devicegraph. In script mode a commit it done automatically if needed.

Modi Operandi of Commands

Many commands operate significantly different based on the provided options.

For example when creating a file system using create xfs /dev/sdb1 the XFS is created on the partition /dev/sdb1. On the other hand the command create xfs /dev/sdb --size 10G will create a 10 GiB partition on /dev/sdb are the XFS on the new partition. And the command create xfs will take a device from the stack and create the XFS on that device.

GLOBAL OPTIONS

-q, --quiet

Suppress normal output. Error messages will still be printed, though.

-v, --verbose

Increase verbosity.

-t, --table-style style

Specifies table style. Table style is identified by an integer number.

--color

Use colors colors in output.

--no-color

Do not use colors colors in output.

--dry-run

Do not commit anything to disk.

--rootprefix path

Prepend various path (mount points and files in /etc) with a rootprefix. Useful when running in a installation or rescue system.

-a, --activate

Activate storage systems at startup. Useful when running in a installation or rescue system.

--yes

Do not prompt for confirmation but assume the answer yes. Use with extreme caution.

-h, --help format

Print help and exit.

--version

Print version and exit.

COMMANDS

Barrel provides a number of commands. Many commands have specific options, which are listed in this section. These command-specific options must be specified after the name of the command. For several commands some options are mandatory.

[

Starts an array construction by pushing a mark on the stack.

]

Ends an array construction by creating a new array from the objects on the stack upto the next mark, removing the objects and the mark from the stack and finally pushing the new array onto the stack.

clear

Clears the stack.

commit

Commits changes to disk and quits.

create encryption [device]

Creates a new encryption device.

-t, --type type

Set encryption type. Possible values are luks1 and luks2.

-n, --name name

Name of device-mapper device.

--label label

Label of device-mapper device. Only for LUKS2.

--activate-by type

Set the activate-by type used in /etc/crypttab. Possible values are device, path, id, uuid and label (only for LUKS2). The default is usually uuid. If the selected type is not available the fallback is device.

--activate-options options

Options in /etc/crypttab for the encryption.

--pool-name name

Name of pool from which to take underlying device.

-s, --size size

Approximate size of resulting encryption device.

--key-file

Set a key file. The key file is used during commit and in /etc/crypttab. Also the key file must already exist.

--key-size

Set the key size in in bits. Must be at least a multiple of 8. See cryptsetup for more details.

--cipher

Set the cipher. See cryptsetup for more details.

--pbkdf

Set the PBKDF (Password-Based Key Derivation Function). See cryptsetup for more details.

--no-crypttab

Do not add the encryption in /etc/crypttab.

--force

Force creation if block device is in use.

Possible Modi Operandi are:

Pool

The encryption device is created on a new partition on a block device from the pool. The options --pool-name and --size are required.

Block Device

The encryption device is created directly on the provided block device. The option --size is not allowed.

Partitionable

The encryption device is created on a new partition on the provided block device, which must be partitionable. The option --size is required.

Block Device from Stack

The encryption device is created directly on the block device from the stack. The option --size is not allowed.

Partitionable from Stack

The encryption device is created on a new partition on the block device from the stack, which must be partitionable. The option --size is required.

create filesystem [device]

Creates a new file system.

-t, --type type

Set file system type. Possible values are bcachefs, btrfs, exfat, ext2, ext3, ext4, f2fs, jfs, nilfs2, ntfs, reiserfs, swap, udf, vfat, xfs.

Not all file systems may be available on the system.

-l, --label label

Set label of file system.

-p, --path path

Path to mount the file system.

For swap the path may be 'swap' or 'none'.

--mount-by type

Set the mount-by type used in /etc/fstab. Possible values are device, path, id, uuid and label. The default is usually uuid. For some devices it is different, e.g. for LVM logical volumes it is device since LVM has stable device names. If the selected type is not available the fallback is device.

--mount-options options

Mount options for the file system.

--mkfs-options options

Options for mkfs command. The options are injected as-is to the command so must be properly quoted.

--tune-options options

Options for the file system tune command. The options are injected as-is to the command so must be properly quoted. Only supported for ext2, ext3 and ext4.

--pool-name options

Name of pool from which to take underlying device.

-s, --size size

Approximate size of the block device or sum of the sizes of the block devices for the file system.

Due to file system metadata and for btrfs also data duplication the usable space of the resulting file system can be much smaller.

-d, --devices number

For btrfs the number of underlying devices for the file system. Default is 1. The special value of 'max' uses all devices provided or all devices of the pool.

--profile profile

Btrfs profiles for data and metadata. Either one profile can be provided for both data and metadata, or two profiles separated by comma, the first for data and the second for metadata.

--no-fstab

Do not add the file system in /etc/fstab.

--force

Force creation if block device is in use.

Possible Modi Operandi are:

Pool

The file system is created on a new partition on a block device from the pool. The options --pool-name and --size are required.

Block Device

The file system is created directly on the provided block device. The option --size is not allowed.

Partitionable

The file system is created on a new partition on the provided block device, which must be partitionable. The option --size is required.

Block Devices from Stack

The file system is created directly on block devices from the stack. The option --size is not allowed. The top object on the stack must be a block device or an array of block devices.

Partitionables from Stack

The file system is created on new partitions on the block devices from the stack. The option --size is required. The top object on the stack must be a partitionable block device or an array of partitionable block devices.

create lv

Creates a new LVM logical volume.

-v, --vg-name vg-name

Name of volume group to use.

-n, --name name

Name of new logical volume.

-s, --size size

Approximate size of resulting logical volume.

--stripes stripes

Number of stripes for the logical volume. Default is 1. The special value of 'max' uses all underlying devices of the volume group.

--stripe-size stripe-size

Stripe size.

Possible Modi Operandi are:

Volume Group

The logical volume is created on the provided volume group. The option --vg-name is required.

Volume Group from Stack

The logical volume is created on the volume group from the stack.

create partition-table [device]

Creates a new partition table.

-t, --type type

Set partition table type. Possible values are gpt and ms-dos.

--force

Force creation if block device is in use.

Possible Modi Operandi are:

Partitionable

The partition table is created on the provided block device, which must be partitionable.

Partitionable from Stack

The partition table is created on the block device from the stack, which must be partitionable.

create pool [devices]

Creates a new pool containing devices.

-n, --name name

Name of pool.

create raid [devices]

Creates a new RAID.

-l, --level level

Set RAID level. Possible values are linear, 0, stripe, 1, mirror, 4, 5, 6 and 10.

-n, --name name

Set name of RAID.

--pool-name name

Name of pool from which to take underlying devices.

-s, --size size

Approximate size of resulting RAID.

--metadata metadata

RAID metadata version. Possible values are 1.0, 1.1 and 1.2, although other values might work. Without the option the default of mdadm is used (which is 1.2 at present).

-d, --devices number

Number of RAID and spare devices. Possible formats are:

r

Create a RAID with r RAID devices and no space devices.

r+s

Create a RAID with r RAID devices and s spare devices.

+s

Create a RAID with n-s RAID devices and s space devices.

The default is to use n. n is the number of devices provided or devices of the pool.

--chunk-size chunk-size

Chunk size.

--force

Force creation if block devices are in use.

Possible Modi Operandi are:

Pool

The RAID is created on new partitions on block devices from the pool. The options --pool-name and --size are required.

Block Devices

The RAID is created directly on the provided block devices. The option --size is not allowed.

Partitionables

The RAID is created on new partitions on the provided block devices, which must be partitionable. The option --size is required.

create vg [devices]

Creates a new LVM volume group.

-n, --name name

Name of new volume group.

--pool-name name

Name of pool from which to take underlying devices.

-s, --size size

Approximate size of resulting volume group.

-d, --devices number

Number of underlying devices for the volume group. Default is 1. The special value of 'max' uses all devices provided or all devices of the pool.

--extent-size extent-size

Extent size.

--force

Force creation if block devices are in use.

Possible Modi Operandi are:

Pool

The volume group is created on new partitions on block devices from the pool. The options --pool-name and --size are required.

Block Devices

The volume group is created directly on the provided block devices. The option --size is not allowed.

Partitionables

The volume group is created on new partitions on the provided block devices, which must be partitionable. The option --size is required.

Block Devices from Stack

The volume group is created directly on the block devices from the stack. The option --size is not allowed. The top object on the stack must be a block device or an array of block devices.

Partitionables from Stack

The volume group is created on new partitions on the block devices from the stack. The option --size is required. The top object on the stack must be a partitionable block device or an array of partitionable block devices.

dup

Duplicates the top object of the stack.

exch

Exchanges the two top objects of the stack.

extend pool devices

Adds devices to a pool.

-n, --name name

Name of pool.

help [main-command [sub-command]]

Shows help.

load devicegraph

Loads the staging devicegraph from a file.

This function is still in development. Use with great care.

-n, --name name

Name of devicegraph file.

-m, --mapping name

Name of mapping file.

load pools

Explicitly loads pools from /etc/barrel/pools.json. Pools are automatically loaded at startup.

pop

Removes the top object from the stack.

quit

Quits barrel.

reduce pool devices

Removes devices from a pool.

-n, --name name

Name of pool.

remove device devices

Removes a device and all device and file systems using it.

When removing a RAID or encryption device the underlying partitions are also removed. This is not possible if it would cause used partitions to be renumbered, e.g. logical partitions on an MS-DOS partition table.

--keep-partitions

Keep underlying partitions.

remove pool devices

Removes a pool.

-n, --name name

Name of pool.

rename pool

Renames a pool.

-o, --old-name name

Old name of pool.

-n, --new-name name

New name of pool.

save devicegraph

Saves the devicegraph to a file.

-n, --name name

Name of devicegraph file.

--probed

Save the probed instead of the staging devicegraph.

save pools

Explicitly saves pools in /etc/barrel/pools.json. Pools are also saved during commit if modified.

show commit

Shows commit actions.

show dasds

Shows DASDs.

--probed

Show DASDs of the probed instead of the staging devicegraph.

--no-partitions

Do not show partitions on the DASDs.

show disks

Shows disks.

--probed

Show disks of the probed instead of the staging devicegraph.

--no-partitions

Do not show partitions on the disks.

show encryptions

Shows encryption devices.

--probed

Show encryption devices of the probed instead of the staging devicegraph.

show filesystems

Shows file systems.

--probed

Show file systems of the probed instead of the staging devicegraph.

show multipaths

Shows multipath devices.

--probed

Show multipath devices of the probed instead of the staging devicegraph.

--no-partitions

Do not show partitions on the multipath devices.

show pools

Shows pools.

--probed

Use the probed instead of the staging devicegraph for finding devices of the pools.

Devices that are currently not usable since they do not have a partition table are marked with an '!'.

show raids

Shows RAIDs.

--probed

Show RAIDs of the probed instead of the staging devicegraph.

--no-partitions

Do not show partitions on the RAIDs.

show tree devices

Shows a tree of block devices for the provided devices.

--up

Show tree moving up from the devices.

--down

Show tree moving down from the devices.

--probed

Show tree of the probed instead of the staging devicegraph.

show vgs

Shows LVM volume groups.

--probed

Show volume groups of the probed instead of the staging devicegraph.

stack

Prints the stack.

undo

Restores the staging devicegraph to the last backup.

EXAMPLES

barrel create xfs /dev/sdb1 --path /test

Create an XFS on /dev/sdb1 and mount it at /test.

barrel create xfs /dev/sdb --size 10G --path /test

Create a 10 GiB partition on /dev/sdb with an XFS and mount it at /test.

barrel create btrfs --size 1TiB --pool "SSDs (512 B)" --devices 2 --profiles raid0,raid1 --path /test

Create two 0.5 TiB partitions on two devices from the pool "SSDs (512 B)", create a btrfs with raid0 profile for data and raid1 profile for metadata on those partitions and mount it at /test.

barrel create raid1 /dev/sd[bc]1 xfs --path /test

Create a RAID1 on /dev/sdb1 and /dev/sdc1 with an XFS and mounted at /test.

barrel create raid5 --size 1TiB --pool "HDDs (512 B)" --devices 3+1 xfs --path /test

Create a 1 TiB RAID5 with 3 devices and 1 spare from devices in the pool "HDDs (512 B)" and an XFS on the RAID mounted at /test.

barrel create vg --name vg1 --size 1TiB /dev/sdb lv --name lv1 --size 100G xfs --path /test

Create a new 1 TiB partition on /dev/sdb, create a volume group with name vg1 using the partition, create a logical volume with name lv1 and size 100G within the volume group and finally create an XFS on the logical volume and mount it at /test.

FILES

/etc/barrel/pools.json

JSON file defining pools.

/var/log/barrel.log

Logfile. Please include this file in bug reports.

BUGS AND MISSING FEATURES

•Validation of input is unfinished.

•Missing tools are not installed on demand.

•Tools doing automounts, e.g. systemd and desktop environments, can cause race conditions.

•Incomplete support for multipath, BIOS RAIDS and DASDs.

•Tab completion in the interactive mode is not context aware.

HOMEPAGE

http://github.com/openSUSE/barrel/

AUTHORS

Arvin Schnell <aschnell@suse.com>

SEE ALSO

parted(8), mkfs(8), mount(8), mdadm(8), lvm(8), cryptsetup(8), fstab(5), crypttab(5), mdadm.conf(5)

2024-07-16 0.2.8