Attachments

Attaching a volume or snapshot makes it accessible to a client under the /dev/storpool and /dev/storpool-byid directories. Volumes can be attached as read-only or read-write. Snapshots are always attached read-only.

Command parameters

When performing attaching and detaching operations there are three types of parameters:

  • Mandatory: volume or snapshot.

  • Mandatory: client or here.

  • Optional: any other parameter.

The order in which these parameters are added to a command is not important.

Attach

You can perform attachment operations on the command line using the storpool attach command. It has the following parameters:

client

Specify the ID of a client to which the volume or snapshot should be attached. You can obtain a client ID using the storpool client status command; see Client.

here

Attach a volume or snapshot to the node you are currently connected to.

volume

Specify the name of the volume to be attached. You can obtain volume names using the storpool volume list command; see Listing all volumes.

snapshot

Specify the name of the snapshot to be attached. You can obtain snapshot names using the storpool snapshot list command; see Listing snapshots.

mode

Specify the read/write mode: either rw (read/write) or ro (read-only).

allowRemoteExported

Allow attaching of remote volumes.

list

List the current attachments.

noWait

Do not wait for the client.

timeout

Seconds to wait for the client to appear.

Detach

You can detach volumes and snapshots (make them no longer visible to a client) using the storpool detach command. It has the all, client, force, here, noWait, snapshot, and volume parameters. You can use the all parameter when you need to detach from all clients. The rest of the parameters are the same as those for the storpool attach command.

Examples

Attaching

Use the following command to attach a volume testvolume to a client with ID 1. This creates the block device /dev/storpool/testvolume:

# storpool attach volume testvolume client 1
OK

To attach a volume or snapshot to the node you are currently connected to:

# storpool attach volume testvolume here
OK
# storpool attach snapshot testsnap here
OK

By default, this command will block until the volume is attached to the client and the /dev/storpool/<volumename> symlink is created. For example, if the storpool_block service has not been started the command will wait indefinitely. To set a timeout for this operation:

# storpool attach volume testvolume here timeout 10
OK

To completely disregard the readiness check:

# storpool attach volume testvolume here noWait
OK

Note

The use of noWait is discouraged in favor of the default behaviour of the attach command.

Attaching a volume will create a read-write block device attachment by default. To attach it read-only:

# storpool attach volume testvolume2 client 12 mode ro
OK

To list all attachments:

# storpool attach list
-------------------------------------------------------------------
| client | volume               | globalId | mode | tags          |
-------------------------------------------------------------------
|     11 | testvolume           | d.n.a1z  | RW   | vc-policy=no  |
|     12 | testvolume1          | d.n.c2p  | RW   | vc-policy=no  |
|     12 | testvolume2          | d.n.uwp  | RO   | vc-policy=no  |
|     14 | testsnap             | d.n.s1m  | RO   | vc-policy=no  |
-------------------------------------------------------------------

Detaching

To detach a volume you need to specify its name and the client ID. If the command is being executed on the same client ID (1 in the example below) you can use the here parameter instead:

# storpool detach volume testvolume client 1

If a volume is actively being written or read from, a detach operation will fail:

# storpool detach volume testvolume client 11
Error: 'testvolume' is open at client 11

In this case the detach could be forced; beware that forcing a detachment is discouraged:

# storpool detach volume testvolume client 11 force yes
OK

Attention

Any operations on the volume will receive an IO Error when it is forcefully detached. Some mounted filesystems lead to kernel panic when a block device disappears when there with live operations, thus be extra careful if these filesystems are mounted on a hypervisor node directly.

If a volume or snapshot is attached to more than one client it could be detached from all nodes with a single command:

# storpool detach volume testvolume all
OK
# storpool detach snapshot testsnap all
OK

More information

You can also view and manage attachments using the Graphical user interface and the REST API.