Chapter 7. Performing operations with the Shared File Systems service (manila)

Cloud users can create and manage shares from the available share types in the Shared File Systems service (manila). You use the Shared File Systems service command-line client to manage shared file systems.

7.2. Creating NFS, CephFS, or CIFS shares

Cloud users can create CephFS-NFS, native CephFS, or CIFS shares to read and write data.

When you create a share, you must specify the share protocol and the size of the share in gigabytes. You can also include the share-type, share-network and name command options:

$ manila create [--share-type <share_type>] \
        [--share-network <share_network>]  \
        [--name <share_name>] <share_protocol> <GB>

In the command example, replace the following values:

<share_type>: Applies settings associated with the specified share type:
- Optional. If you do not specify a share type, the default share type is used.
<share_network>: The name of the share network:
- Required if the share type has driver_handles_share_servers set to true.
- Unsupported if the share type has driver_handles_share_servers set to false.
- Unsupported for CephFS-NFS and native CephFS. These protocols do not support share types that have driver_handles_share_servers set to true.
<share_name>: The name of the share:
- Optional. Shares are not required to have a name, and the name does not need to be unique.
<share_protocol>: The share protocol you want to use:
- For CephFS-NFS, replace <share_protocol> with nfs.
- For native CephFS, replace <share_protocol> with cephfs.
- For other storage back ends that support NFS or CIFS protocols, for example, NetApp or Dell EMC storage back ends, replace <share_protocol> with nfs or cifs.
<GB>: The size of the share in gigabytes.

7.2.1. Creating NFS or CIFS shares with DHSS=true

When cloud administrators activate self-service share networks by using the share type extra specification, driver_handles_share_servers=true, cloud users can add their own security services to a share network to create and export NFS or CIFS shares. The native CephFS protocol does not support share networks.

To add a security service, you must create a share network and a security service resource to represent your Active Directory server. You can then associate the security service to the share network to create and export NFS or CIFS shares.

Procedure

Create a share network:
```
$ manila share-network-create --name <network-name> \
    --neutron-net-id <25d1e65c-d961-4f22-9476-1190f55f118f> \
    --neutron-subnet-id <8ba20dce-0ca5-4efd-bf1c-608d6bceffe1>
```
- Replace <network-name> with the share network name that you want to use for your NFS or CIFS shares.
- Replace the neutron-net-id and neutron-subnet-id with the correct values for your share network.

Create a security service resource to represent your Active Directory server:

$ manila security-service-create <active_directory> \
          --dns-ip <192.02.12.10> \
          --domain <domain-name.com> \
          --user <Administrator> \
          --password <password> \
          --name <AD-service>

Replace the values in angle brackets <> with the correct details for your security service resource.

Associate the security service resource to the share network:

$ manila share-network-security-service-add \
  <network-name> <AD-service>

Create an NFS or CIFS share:

10 GB NFS example:

$ manila create --name <nfs-share> --share-type <netapp> \
    --share-network <nfs-network> nfs 10

20 GB CIFS example:
```
$ manila create --name <cifs-share> --share-type dhss_true \
    --share-network <cifs-network> cifs 20
```
- Replace the values in angle brackets <> with the correct details for your NFS or CIFS share.

7.2.2. Creating NFS, CephFS, or CIFS shares with DHSS=false

When cloud administrators deactivate self-service share networks by using the share type extra specification, driver_handles_share_servers=false, they must pre-configure an Active Directory service to the storage system. For information about how to perform this configuration, see the storage vendor’s documentation.

When DHSS=false, the shared storage network is pre-configured by the cloud administrator, and cloud users can create shares without using the share-network command option.

Procedure

Create an NFS, native CephFS, or CIFS share when DHSS=false. These examples specify a name, but they do not specify the share-type or share-network. They use the default share type and the shared storage network configured by the cloud administrator:
- Create a 10 GB NFS share named share-01.
```
$ manila create --name share-01 nfs 10
```
- Create a 15 GB native CephFS share named share-02:
```
$ manila create --name share-02 cephfs 15
```
- Create a 20 GB CIFS share named share-03:
```
$ manila create --name share-03 cifs 20
```

7.3. Listing shares and exporting information

To verify that you have successfully created NFS, CephFS, or CIFS shares in the Shared File Systems service (manila), complete the following steps to list the shares and view their export locations and parameters.

Procedure

List the shares:

$ manila list

+--------------------------------------+----------+-----+-----------+
| ID                                   | Name     | ... | Status    ...
+--------------------------------------+----------+-----+-----------+
| 8c3bedd8-bc82-4100-a65d-53ec51b5fe81 | share-01 | ... | available ...
+--------------------------------------+----------+-----+-----------+

View the export locations of the share:

$ manila share-export-location-list <share>

 +------------------------------------------------------------------
 | Path
 |  198.51.100.13:/volumes/_nogroup/e840b4ae-6a04-49ee-9d6e-67d4999fbc01
 +------------------------------------------------------------------

Replace <share> with either the share name or the share ID.

View the parameters for the share:
```
$ manila share-export-location-show <share-id>
```
Note
You use the export location to mount the share, as described in Section 7.8.2, “Mounting NFS, native CephFS, or CIFS shares”.

7.4. Creating a snapshot of data on a shared file system

A snapshot is a read-only, point-in-time copy of data on a share. You can use a snapshot to recover data lost through accidental data deletion or file system corruption. Snapshots are more space efficient than backups, and they do not impact the performance of the Shared File Systems service (manila).

Prerequisites

The snapshot_support parameter must equal true on the parent share. You can run the following command to verify:
```
$ manila show | grep snapshot_support
```

Procedure

As a cloud user, create a snapshot of a share:

$ manila snapshot-create [--name <snapshot_name>] <share>

Replace <share> with the name or ID of the share for which you want to create a snapshot.

Optional: Replace <snapshot_name> with the name of the snapshot.

Example output

+-------------------+--------------------------------------+
| Property      	| Value                            	|
+-------------------+--------------------------------------+
| id            	| dbdcb91b-82ba-407e-a23d-44ffca4da04c |
| share_id      	| ee7059aa-5887-4b87-b03e-d4f0c27ed735 |
| share_size    	| 1                                	|
| created_at    	| 2022-01-07T14:20:55.541084       	|
| status        	| creating                         	|
| name          	| snapshot_name                    	|
| description   	| None                             	|
| size          	| 1                                	|
| share_proto   	| NFS                              	|
| provider_location | None                             	|
| user_id       	| 6d414c62237841dcbe63d3707c1cdd90 	|
| project_id    	| 041ff9e24eba469491d770ad8666682d 	|
+-------------------+--------------------------------------+

Confirm that you created the snapshot:
```
$ manila snapshot-list --share-id <share>
```
Replace <share> with the name or ID of the share from which you created the snapshot.

7.4.2. Deleting a snapshot

When you create a snapshot of a share, you cannot delete the share until you delete all of the snapshots created from that share.

Procedure

Identify the snapshot you want to delete and retrieve its ID:
```
$ manila snapshot-list
```
Delete the snapshot:
```
$ manila snapshot-delete <snapshot>
```
Note
Repeat this step for each snapshot that you want to delete.
After you delete the snapshot, run the following command to confirm that you deleted the snapshot:
```
$ manila snapshot-list
```

7.5. Connecting to a shared network to access shares

When the driver_handles_share_servers parameter (DHSS) equals false, shares are exported to the shared provider network that the cloud administrator made available. As an end user, you must connect your client, such as a Compute instance, to the shared provider network to access your shares.

In this example procedure, the shared provider network is called StorageNFS. StorageNFS is configured when director deploys the Shared File Systems service (manila) with the CephFS-NFS back end. Follow similar steps to connect to the network made available by your cloud administrator.

Note

The steps in the example procedure use IPv4 addressing, but the steps are identical for IPv6.

Procedure

Create a security group for the StorageNFS port that allows packets to egress the port but does not allow ingress packets from unestablished connections:

$ openstack security group create no-ingress -f yaml
created_at: '2018-09-19T08:19:58Z'
description: no-ingress
id: 66f67c24-cd8b-45e2-b60f-9eaedc79e3c5
name: no-ingress
project_id: 1e021e8b322a40968484e1af538b8b63
revision_number: 2
rules: 'created_at=''2018-09-19T08:19:58Z'', direction=''egress'', ethertype=''IPv4'',
 id=''6c7f643f-3715-4df5-9fef-0850fb6eaaf2'', updated_at=''2018-09-19T08:19:58Z''
 created_at=''2018-09-19T08:19:58Z'', direction=''egress'', ethertype=''IPv6'',
 id=''a8ca1ac2-fbe5-40e9-ab67-3e55b7a8632a'', updated_at=''2018-09-19T08:19:58Z''

Create a port on the StorageNFS network with security enforced by the no-ingress security group.

$ openstack port create nfs-port0 \
  --network StorageNFS \
  --security-group no-ingress -f yaml

admin_state_up: UP
allowed_address_pairs: ''
binding_host_id: null
binding_profile: null
binding_vif_details: null
binding_vif_type: null
binding_vnic_type: normal
created_at: '2018-09-19T08:03:02Z'
data_plane_status: null
description: ''
device_id: ''
device_owner: ''
dns_assignment: null
dns_name: null
extra_dhcp_opts: ''
fixed_ips: ip_address='198.51.100.160', subnet_id='7bc188ae-aab3-425b-a894-863e4b664192'
id: 7a91cbbc-8821-4d20-a24c-99c07178e5f7
ip_address: null
mac_address: fa:16:3e:be:41:6f
name: nfs-port0
network_id: cb2cbc5f-ea92-4c2d-beb8-d9b10e10efae
option_name: null
option_value: null
port_security_enabled: true
project_id: 1e021e8b322a40968484e1af538b8b63
qos_policy_id: null
revision_number: 6
security_group_ids: 66f67c24-cd8b-45e2-b60f-9eaedc79e3c5
status: DOWN
subnet_id: null
tags: ''
trunk_details: null
updated_at: '2018-09-19T08:03:03Z'

Note

In this example, the StorageNFS subnet on the StorageNFS network assigned IP address 198.51.100.160 to nfs-port0. For more information about the StorageNFS subnet, see Configuring the shared provider StorageNFS network in Deploying Red Hat Ceph Storage and Red Hat OpenStack Platform together with director.

Add nfs-port0 to a Compute instance.
```
$ openstack server add port instance0 nfs-port0
$ openstack server list -f yaml
- Flavor: m1.micro
  ID: 0b878c11-e791-434b-ab63-274ecfc957e8
  Image: manila-test
  Name: demo-instance0
  Networks: demo-network=198.51.100.4, 10.0.0.53; StorageNFS=198.51.100.160
  Status: ACTIVE
```
In addition to its private and floating addresses, the Compute instance is assigned a port with the IP address 198.51.100.160 on the StorageNFS network. You can use this IP address to mount NFS shares when access is granted to that address for the shares.
Note
You might need to adjust the networking configuration on the Compute instance and restart the services for the Compute instance to activate an interface with this address.

7.6. Configuring an IPv6 interface between the network and an instance

When the shared network to which shares are exported uses IPv6 addressing, you might experience an issue with DHCPv6 on the secondary interface. If this issue occurs, configure an IPv6 interface manually on the instance.

Prerequisites

Connection to a shared network to access shares

Procedure

Configure the IPv6 interface address:

$ sudo ip address add fd00:fd00:fd00:7000::c/64 dev eth1

Activate the interface:
```
$ sudo ip link set dev eth1 up
```
Ping the IPv6 address in the export location of the share to test interface connectivity:
```
$ ping -6  fd00:fd00:fd00:7000::21
```
Alternatively, verify that you can reach the NFS server through Telnet:
```
$ sudo dnf install -y telnet
$ telnet fd00:fd00:fd00:7000::21 2049
```

7.7. Granting share access for end-user clients

You must grant end-user clients access to the share so that users can read data from and write data to the share.

You grant a client compute instance access to an NFS share through the IP address of the instance. The user rules for CIFS shares and cephx rules for CephFS shares follow a similar pattern. With user and cephx access types, you can use the same clientidentifier across multiple clients, if required.

Before you can mount a share on a client, such as a compute instance, you must grant the client access to the share by using a command similar to the following command:

$ manila access-allow <share> <accesstype> \
  --access-level <accesslevel>  <clientidentifier>

Replace the following values:

share: The share name or ID of the share created, as described in Section 7.2, “Creating NFS, CephFS, or CIFS shares”.
accesstype: The type of access to be requested on the share. Some types include:
- user: Use to authenticate by user or group name.
- ip: Use to authenticate an instance through its IP address.
- cephx: Use to authenticate by native CephFS client username.
  Note
  The type of access depends on the protocol of the share. For CIFS, you can use user. For NFS shares, you must use ip. For native CephFS shares, you must use cephx.
accesslevel: Optional; the default is rw.
- rw: Read-write access to shares.
- ro: Read-only access to shares.
clientidentifier: Varies depending on accesstype.
- Use an IP address for ip accesstype.
- Use a CIFS user or group for user accesstype.
- Use a username string for cephx accesstype.

7.7.1. Granting access to an NFS share

Cloud users can provide access to NFS shares through IP addresses.

Note

You can use the following procedure with IPv4 or IPv6 addresses.

Procedure

Retrieve the IP address of the client compute instance where you plan to mount the share. Make sure that you select the IP address that corresponds to the network that can reach the shares. In this example, it is the IP address of the StorageNFS network:

$ openstack server list -f yaml
- Flavor: m1.micro
  ID: 0b878c11-e791-434b-ab63-274ecfc957e8
  Image: manila-test
  Name: demo-instance0
  Networks: demo-network=198.51.100.4, 10.0.0.53;
  StorageNFS=198.51.100.160
  Status: ACTIVE

$ manila access-allow <share> ip 198.51.100.160

Note

Access to the share has its own ID, accessid.

+-----------------+---------------------------------------+
| Property        | Value                                 |
+-----------------+---------------------------------------+
| access_key      | None
| share_id        | db3bedd8-bc82-4100-a65d-53ec51b5cba3
| created_at      | 2018-09-17T21:57:42.000000
| updated_at      | None
| access_type     | ip
| access_to       | 198.51.100.160
| access_level    | rw
| state           | queued_to_apply
| id              | 875c6251-c17e-4c45-8516-fe0928004fff
+-----------------+---------------------------------------+

Verification

Verify that the access configuration was successful:

$ manila access-list <share>

+--------------+-------------+--------------+--------------+--------+ ...
| id           | access_type | access_to    | access_level | state  | ...
+--------------+-------------+--------------+--------------+--------+
| 875c6251-... | ip          | 198.51.100.160 | rw       	 | active | ...
+--------------+------------+--------------+--------------+---------+ ...

7.7.2. Granting access to a native CephFS share

Cloud users can provide access to native CephFS shares through Ceph client usernames. The Shared File Systems service (manila) prevents the use of pre-existing Ceph users so you must create unique Ceph client usernames.

To mount a share, you need a Ceph client username and an access key. You can retrieve access keys by using the Shared File Systems service API. By default, access keys are visible to all users in a project namespace. You can provide the same user with access to different shares in the project namespace. Users can then access the shares by using the CephFS kernel client on the client machine.

Important

Use the native CephFS driver with trusted clients only. For information about native CephFS back-end security, see Native CephFS back-end security in Deploying Red Hat Ceph Storage and Red Hat OpenStack Platform together with director.

Procedure

Grant users access to the native CephFS share:
```
$ manila access-allow <share> cephx <user>
```
- Replace <share> with either the share name or the share ID.
- Replace <user> with the cephx user.
Collect the access key for the user:
```
$ manila access-list <share>
```

7.7.3. Granting access to a CIFS share

Cloud users grant access to CIFS shares through usernames that exist in the Active Directory service. The Shared File Systems service (manila) does not create new users on the Active Directory server. It only validates usernames through the security service, and access rules with invalid user names result in an error status.

If the cloud administrator sets the value of the driver_handles_share_servers parameter (DHSS) to true, then the cloud user configures the Active Directory service by adding a security service. If the cloud administrator sets the value of the DHSS parameter to false, then the cloud administrator configures the Active Directory service and associates it with the storage network.

To mount a share, you must specify the user’s Active Directory username and password. You cannot obtain this password through the Shared File Systems service.

Procedure

Grant users access to a CIFS share:
```
$ manila access-allow <share> user <user>
```
- Replace <share> with either the share name or the share ID.
- Replace <user> with the username corresponding to the Active Directory user.

7.7.4. Revoking access to a share

The owner of a share can revoke access to the share for any reason. Complete the following steps to revoke access that was previously granted to a share.

Procedure

Revoke access to a share:

$ manila access-deny <share> <access-id>

Replace <share> with either the share name or the share ID.

Replace <access-id> with the access ID of the share.

For example:

$ manila access-list share-01
+--------------+-------------+--------------+--------------+--------+
| id           | access_type | access_to    | access_level | state  | ...
+--------------+-------------+--------------+--------------+--------+ ...
| 875c6251-... | ip          | 198.51.100.160 | rw         | active | ...
+--------------+-------------+--------------+--------------+--------+

$ manila access-deny share-01 875c6251-c17e-4c45-8516-fe0928004fff

$ manila access-list share-01

+--------------+------------+--------------+--------------+--------+ ...
| id           | access_type| access_to    | access_level | state  | ...
+--------------+------------+--------------+--------------+--------+ ...
+--------------+------------+--------------+--------------+--------+ ...

Note

If you have an existing client that has read-write permissions, you must revoke their access to a share and add a read-only rule if you want the client to have read-only permissions.

7.8. Mounting shares on compute instances

After you grant share access to clients, the clients can mount and use the shares. Any type of client can access shares as long as there is network connectivity to the client.

The steps used to mount an NFS share on a virtual compute instance are similar to the steps to mount an NFS share on a bare-metal compute instance. For more information about how to mount shares on OpenShift containers, see Product Documentation for OpenShift Container Platform.

Note

Client packages for the different protocols must be installed on the Compute instance that mounts the shares. For example, for the Shared File Systems service with CephFS-NFS, the NFS client packages must support NFS 4.1.

7.8.2. Mounting NFS, native CephFS, or CIFS shares

When you create NFS, native CephFS, or CIFS shares and grant share access to end-user clients, users can mount the shares on the client to enable access to data, as long as there is network connectivity.

Prerequisites

To mount NFS shares, the nfs-utils package must be installed on the client machine.
To mount native CephFS shares, the ceph-common package must be installed on the client machine. Users access native CephFS shares by using the CephFS kernel client on the client machine.
To mount CIFS shares, the cifs-utils package must be installed on the client machine.

Procedure

$ openstack server ssh demo-instance0 --login user

Mount an NFS share. Refer to the following example for sample syntax:
```
$ mount -t nfs \
  -v <198.51.100.13:/volumes/_nogroup/e840b4ae-6a04-49ee-9d6e-67d4999fbc01>  \
  /mnt
```
- Replace <198.51.100.13:/volumes/_nogroup/e840b4ae-6a04-49ee-9d6e-67d4999fbc01> with the export location of the share.
- Retrieve the export location as described in Section 7.8.1, “Listing share export locations”.
Mount a native CephFS share. Refer to the following example for sample syntax:
```
$  mount -t ceph \
  <192.0.2.125:6789,192.0.2.126:6789,192.0.2.127:6789:/volumes/_nogroup/4c55ad20-9c55-4a5e-9233-8ac64566b98c> \
  -o name=<user>,secret='<AQA8+ANW/<4ZWNRAAOtWJMFPEihBA1unFImJczA==>'
```
- Replace <192.0.2.125:6789,192.0.2.126:6789,192.0.2.127:6789:/volumes/_nogroup/4c55ad20-9c55-4a5e-9233-8ac64566b98c> with the export location of the share.
- Retrieve the export location as described in Section 7.8.1, “Listing share export locations”.
- Replace <user> with the cephx user who has access to the share.
- Replace the secret value with the access key that you collected in Section 7.7.2, “Granting access to a native CephFS share”.
Mount a CIFS share. Refer to the following example for sample syntax:
```
$  mount -t cifs \
  -o user=<user>,pass=<password> \
  <\\192.0.2.128/share_11265e8a_200c_4e0a_a40f_b7a1117001ed>
```
- Replace <user> with the Active Directory user who has access to the share.
- Replace <password> with the user’s Active Directory password.
- Replace <\\192.0.2.128/share_11265e8a_200c_4e0a_a40f_b7a1117001ed> with the export location of the share.
- Retrieve the export location as described in Section 7.8.1, “Listing share export locations”.

Verification

Verify that the mount command succeeded:
```
$ df -k
```

7.9. Deleting shares

The Shared File Systems service (manila) provides no protections to prevent you from deleting your data. The Shared File Systems service does not check whether clients are connected or workloads are running. When you delete a share, you cannot retrieve it.

Warning

Back up your data before you delete a share.

Prerequisites

If you created snapshots from a share, you must delete all of the snapshots and replicas before you can delete the share. For more information, see Deleting a snapshot.

Procedure

Delete a share:
```
$ manila delete <share>
```
Replace <share> with either the share name or the share ID.

7.10. Listing resource limits of the Shared File Systems service

As a cloud user, you can list the current resource limits. This can help you plan workloads and prepare for any action based on your resource consumption.

Procedure

List the resource limits and current resource consumption for the project:

$ manila absolute-limits
+------------------------------+-------+
| Name                         | Value |
+------------------------------+-------+
| maxTotalReplicaGigabytes     | 1000  |
| maxTotalShareGigabytes       | 1000  |
| maxTotalShareGroupSnapshots  | 50    |
| maxTotalShareGroups          | 49    |
| maxTotalShareNetworks        | 10    |
| maxTotalShareReplicas        | 100   |
| maxTotalShareSnapshots       | 50    |
| maxTotalShares               | 50    |
| maxTotalSnapshotGigabytes    | 1000  |
| totalReplicaGigabytesUsed    | 22    |
| totalShareGigabytesUsed      | 25    |
| totalShareGroupSnapshotsUsed | 0     |
| totalShareGroupsUsed         | 9     |
| totalShareNetworksUsed       | 2     |
| totalShareReplicasUsed       | 9     |
| totalShareSnapshotsUsed      | 4     |
| totalSharesUsed              | 12    |
| totalSnapshotGigabytesUsed   | 4     |
+------------------------------+-------+

7.11. Troubleshooting operation failures

In the event that Shared File Systems (manila) operations, such as create share or create share group, fail asynchronously, as an end user, you can run queries from the command line for more information about the errors.

Chapter 7. Performing operations with the Shared File Systems service (manila)

7.2. Creating NFS, CephFS, or CIFS shares

7.2.1. Creating NFS or CIFS shares with DHSS=true

7.2.2. Creating NFS, CephFS, or CIFS shares with DHSS=false

7.3. Listing shares and exporting information

7.4. Creating a snapshot of data on a shared file system

7.4.2. Deleting a snapshot

7.5. Connecting to a shared network to access shares

7.6. Configuring an IPv6 interface between the network and an instance

7.8. Mounting shares on compute instances

7.8.2. Mounting NFS, native CephFS, or CIFS shares

7.9. Deleting shares

7.10. Listing resource limits of the Shared File Systems service

7.11. Troubleshooting operation failures

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

Making open source more inclusive

About Red Hat

Red Hat legal and privacy links

Red Hat legal and privacy links

Chapter 7. Performing operations with the Shared File Systems service (manila)

7.1. Listing share types

7.2. Creating NFS, CephFS, or CIFS shares

7.2.1. Creating NFS or CIFS shares with DHSS=true

7.2.2. Creating NFS, CephFS, or CIFS shares with DHSS=false

7.3. Listing shares and exporting information

7.4. Creating a snapshot of data on a shared file system

7.4.1. Creating a share from a snapshot

7.4.2. Deleting a snapshot

7.5. Connecting to a shared network to access shares

7.6. Configuring an IPv6 interface between the network and an instance

7.7. Granting share access for end-user clients

7.7.1. Granting access to an NFS share

7.7.2. Granting access to a native CephFS share

7.7.3. Granting access to a CIFS share

7.7.4. Revoking access to a share

7.8. Mounting shares on compute instances

7.8.1. Listing share export locations

7.8.2. Mounting NFS, native CephFS, or CIFS shares

7.9. Deleting shares

7.10. Listing resource limits of the Shared File Systems service

7.11. Troubleshooting operation failures

7.11.1. Fixing create share or create share group failures

7.11.2. Debugging share mounting failures

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

Making open source more inclusive

About Red Hat

Red Hat legal and privacy links

Red Hat legal and privacy links