Creating file shares and mount targets
Create file shares and mount targets in the console, CLI, API, or Terraform.
Before you get started, and try to create mount targets for file shares, make sure that you created a VPC.
You can create file shares and mount targets either of the following ways:
- Create a file share and mount target together,
- Create a file share and add mount target later.
When you create a mount target, its transit encryption type must reflect the share's allowed transit encryption modes. You can create multiple mount targets for the share if it's to be used by resources in different VPCs. You can create one mount target per VPC for the file share.
Customers with special access to preview the new regional file share offering can use the rfs profile to create file shares with regional availability and adjustable throughput values.
Creating a file share in the console
In the IBM Cloud console, you can create a file share with or without a mount target. However, you need to create a mount target when you want to mount the share on a virtual server instance.
Creating a file share in the console
-
In the IBM Cloud console, click the Navigation menu icon
> Infrastructure 
> Storage > File storage shares. A list of file shares displays. -
On the File storage shares for VPC page, click Create. Select Create file share.
-
Enter the following information.
Values for creating a file share Field Value Availability New Beta If you're a customer with special access to preview the new regional file share offering, you can choose between Regional and Single zone data availability. You can't change this property after the share is created.
If you're account is not allow-listed, this field does not appear. Select the location for your zonal file share.Location Beta If you chose Single zone availability, select the geography, region, and zone for the new file share, for example, North America, Dallas (us-south), us-south-2. If you chose regional availability, select the region. For example, Dallas (us-south). Details Name Specify a meaningful name for your file share. The file share name can be up to 63 lowercase alpha-numeric characters and include the hyphen (-), and must begin with a lowercase letter. You can later edit the name if you want. Resource Group Use the default resource group or specify a Resource group. Resource groups help organize your account resources for access control and billing purposes. Tags (optional) Enter any user tags to apply to this file share. As you type, existing tags appear that you can select. For more information about tags, see Add user tags to a file share. Access Management Tags (optional) Enter access management tags that you created in IAM to apply them to this file share. For more information about access management tags, see Access management tags for file shares. Profile The profile is auto-populated based on your data availability selection. For more information, see file Storage profiles.
- If you chose Single zone availability, your file share uses the
dp2profile. Select the size and IOPS for your file share. You can increase the capacity later, and you can also adjust the IOPS as needed. - Beta If you chose regional availability, your file share uses the
rfsprofile. Select the size and bandwidth for your file share. You can increase the capacity later, and you can also adjust the bandwidth as needed.
Mount target access mode Select how you want to manage access to this file share: Security group: Access to the file share is based on security group rules. This option can be used to restrict access to specific virtual server instances. You can also use this option if you want to mount the file share to a virtual server instance in another zone. This option is recommended as you have more control over who can access the data that is stored on the file share. When you choose this type of access, you can also specify the allowed transit encryption modes. Virtual private cloud: Access to the file share is granted to any virtual server instance in the same region. Cross-zone mounting, encryption in transit, cross-zone mounting, and snapshots are not supported when this access mode is selected. Beta This legacy access mode is not supported for regional shares. Allowed transit encryption modes As the share owner, you can specify how you want clients within your account and authorized accounts to connect to your file share. You can select none if you do not want them to use encryption in transit. If you want them to use encryption in transit, select IPsec for a zonal share or Beta stunnel for a regional share. If you select both available options, then the transit encryption type of the first mount target decides the transit encryption types of all future mount targets within the account. - If you chose Single zone availability, your file share uses the
-
The creation of mount targets is optional. You can skip this step if you do not want to create a mount target now. Otherwise, click Create. You can create one mount target per VPC per file share.
-
If you selected security group as the access mode, enter the information as described in the Table 2. This action creates and attaches a virtual network interface to your mount target that identifies the file share with a reserved IP address and applies the rules of the selected Security group. This mount target supports encryption-in-transit and cross-zone mounting.
- Provide a mount target name. The name can be up to 63 lowercase alpha-numeric characters and include the hyphen (-), and must begin with a lowercase letter. You can later edit the name if you want.
- Select an available VPC. The list includes only those VPCs with a subnet in the selected location. The location selection is inherited from the file share (for example, us-south-2).
- A default virtual network interface is generated. You can customize it by clicking the Edit icon
. You can change the name or subnet if you have multiple subnets in the zone. - Click Next.
- Encryption in transit is disabled by default for zonal shares, and it is enabled by default for regional shares. Click the toggle to change the preset value. For more information about this feature, see Encryption in transit - Securing mount connections between file share and host.
- Then, click Next.
- Review your selection, and either click Back to return and update your choices or click Create.
-
If you selected VPC as the access mode, provide a name for the mount target and select a VPC from the list. This mount target can be used to mount the file share on any virtual server instance of the selected VPC in the same zone as the file share. Cross-zone mounting is not supported.
-
-
Encryption at rest. By default, all file shares are encrypted by IBM-managed keys. You can also choose to create an envelop-encryption for your shares with your own keys. If you want to use your own keys, select one of the key management services.
Values for customer-managed encryption for file shares. Field Value Encryption To use customer-managed encryption, select either Key Protect or Hyper Protect Crypto Services. The key management service (KMS) instance includes the root key that is imported to or created in that KMS instance. Encryption service instance If you provisioned multiple KMS instances in your account, select the one that includes the root key that you want to use for customer-managed encryption. Key name Select the root key within the KMS instance that you want to use for encrypting the share. Key ID The field shows the key ID that is associated with the data encryption key that you selected. Customer-managed encryption is not supported during the beta release of the regional file share profile.
-
When all the required information is entered, click Create file share. You return to the File Storage for VPC page, where a message indicates that the file share is provisioning. When the transaction completes, the share status changes to Active.
If you're not ready to order yet or just looking for pricing information, you can add the information that you see in the side panel to an Estimate. For more information about how this feature works, see Estimating your costs.
Creating a mount target in the console
-
In the IBM Cloud console, click the Navigation menu icon
> Infrastructure > Storage > File storage shares. -
Select a file share from the list.
-
On the File shares details page, under Mount targets, click Create.
You must have at least one VPC to create a mount target. If you don't have one, first create a VPC.
-
Depending on the mount target access mode of the share, the Create mount target form looks different.
-
If the share has security group access mode, enter the following information. This action creates and attaches a virtual network interface to your mount target that identifies the file share with a reserved IP address and applies the rules of the selected security group. This mount target supports encryption-in-transit and cross-zone mounting.
- Provide a mount target name. The name can be up to 63 lowercase alpha-numeric characters and include the hyphen (-), and must begin with a lowercase letter. You can later edit the name if you want.
- Select an available VPC. The list includes only those VPCs with a subnet in the selected location. The location selection is inherited from the file share (for example, us-south-2).
- A default virtual network interface is generated. You can customize it by clicking the Edit icon . You can change the name or subnet if you have multiple subnets in the location.
- Click Next.
- Encryption in transit is disabled by default for zonal shares, and it is enabled by default for regional shares. Click the toggle to change the preset value. For more information about this feature, see Encryption in transit - Securing mount connections between file share and host.
- Then, click Next.
-
If the zonal share has VPC as the access mode, provide a name for the mount target and select a VPC from the list. This mount target can be used to mount the file share on any virtual server instance of the selected VPC in the same zone as the file share. Cross-zone mounting is not supported.
-
-
Click Create.
Creating a file share from the CLI
Before you begin
Before you can use the CLI, you must install the IBM Cloud CLI and the VPC CLI plug-in. For more information, see the CLI prerequisites.
If you are a customer with special access to preview the regional file share profile, you can use the rfs profile to create a file share. To access the beta feature, you must set the appropriate environmental variable with the
following command.
export IBMCLOUD_IS_FEATURE_SHARE_DENALI_REGIONAL_AVAILABILITY=true
The CLI returns the properties for "Allowed Access Protocols", "Availability Mode", "Bandwidth", and "Storage Generation" only when this environmental variable is set to "true".
Gathering information from the CLI
Before you run the ibmcloud is share-create command, you can gather information that you need for provisioning a share by viewing information about other file shares, mount targets, and file storage profiles.
| Details | Listing options | What it provides |
|---|---|---|
| File shares | ibmcloud is shares |
List all shares in a region. |
| File share details | ibmcloud is share SHARE_ID |
Review details of a share. |
| File share snapshots | ibmcloud is share-snapshots |
List available snapshots in the zone. |
| File share profiles | ibmcloud is share-profiles |
List all file share profiles in a region. Only dp2 can be used to create file shares. |
| Mount targets | ibmcloud is share-mount-targets SHARE_ID |
List all mount targets for a file share. |
| Subnets | ibmcloud is subnets |
List all subnets. |
| Reserved IP addresses | ibmcloud is subnet-reserved-ips |
List all reserved IP addresses in the subnet. |
| Security Groups | ibmcloud is security-groups |
List all security groups. |
Creating a mount target for a file share from the CLI
To create a mount target for the file share, run the share-mount-target-create command. Before you begin, gather some necessary information.
When you create a mount target, you must specify the file share that it is for. You can use the file share's name or ID. You must specify the VPC, too, either with its ID or name. The VPC must be unique to each mount target. You must also specify the security access group that's going to be used to manage access to the share. The security groups that you associate with a mount target must allow inbound access for the TCP protocol on the NFS port from all servers where you want to mount the share.
Lastly, you must specify values for the options that are needed to create a virtual network interface for the mount target. Use the appropriate CLI commands to list the available subnets, reserved IP addresses in a subnet, security groups to get the information that you need.
The following example creates a mount target with a virtual network interface for a file share that has security group access mode.
$ ibmcloud is share-mount-target-create my-file-share --subnet my-subnet --name my-cli-share-mount-target-1 --vni-name my-share-vni-1 --resource-group-id 6edefe513d934fdd872e78ee6a8e73ef --access-protocol nfs4 --transit-encryption none --vpc my-vpc
Mounting target for share r006-b696742a-92ee-4f6a-bfd7-921d6ddf8fa6 under account Test Account as user test.user@ibm.com...
ID r006-72c81658-35ae-40b7-abab-8480e5050857
Name my-cli-share-mount-target-1
VPC ID Name
r006-243394d6-b192-4e05-bfab-5d0b4e77cf81 my-vpc
Access control mode security_group
Resource type share_mount_target
Virtual network interface ID Name Protocol State Filtering Mode
0717-6dedcf6f-7596-4274-b158-c01f08edb697 my-share-vni-1 auto
Lifecycle state pending
Mount path -
Transit Encryption none
Created 2025-08-01T20:28:50+00:0
Beta When the same command is used to create a mount target for a regional file share, the output looks very similar. The Access Protocol property is also shown.
$ ibmcloud is share-mount-target-create my-regional-file-share --subnet my-subnet --name my-regional-share-mount-target-1 --vni-name my-share-vni-2 --resource-group-id 6edefe513d934fdd872e78ee6a8e73ef --access-protocol nfs4 --transit-encryption none --vpc my-vpc
Mounting target for share r006-749d05eb-9779-4414-b902-553a4fd1421d under account Test Account as user test.user@ibm.com...
ID r006-bc95a3c2-b84b-4186-8c5a-e3dd220abefa
Name my-regional-share-mount-target-1
VPC ID Name
r006-243394d6-b192-4e05-bfab-5d0b4e77cf81 my-vpc
Access control mode security_group
Resource type share_mount_target
Virtual network interface ID Name Protocol State Filtering Mode
0717-24e7dcac-e30f-43cf-9bee-3cab93692690 my-share-vni-2 auto
Lifecycle state pending
Mount path -
Transit Encryption none
Created 2025-08-01T20:45:14+00:00
Access Protocol nfs4
The following example creates a mount target for a zonal file share that has VPC access mode.
$ ibmcloud is share-mount-target-create my-vpc-file-share --vpc cli-vpc-3 --name my-vpc-mount-target --access-protocol nfs4 --transit-encryption none
Mounting target for share r006-10e82e16-ff7f-4ca4-b543-d24084fc03cf under account Test Account as user test.user@ibm.com...
ID r006-71fd953c-8e49-48e8-ab49-5977c324a365
Name my-vpc-mount-target
VPC ID Name
r006-060fbfe6-4d0f-47b0-b9c5-94da8e719e22 cli-vpc-3
Access control mode vpc
Resource type share_mount_target
Virtual network interface
Lifecycle state pending
Created 2025-07-22T22:15:15+00:00
Mount path -
Transit Encryption none
For more information about the command options, see ibmcloud is share-mount-target-create.
Adding supplemental IDs when you create a file share with the CLI
With the CLI, you can set UID and GID values for the --initial-owner-uid and --initial-owner-gid property to control access to your file shares. Wherever you mount the file share, the root
folder uses that user ID and group ID owner. You can set the UID or GID, or both when you create a share.
If you change the supplemental IDs (UID or GID) from the virtual server instance, it is not possible to determine that it was changed. As a result, initial_owner changes only in the file storage system, but the change isn't reflected
in the CLI or API responses.
Table 1 shows UID and GID values that you can set and values that are reserved.
| ID value | Description |
|---|---|
| UID | |
| UID 0 | Reserved for root. |
| UID 1–99 | Reserved for predefined accounts. |
| UID 100–999 | Reserved by the system for administrative system accounts and groups. |
| UID 1000–10000 | Used by applications account. |
| UID 10000+ | Available for user accounts. |
| GID | |
| GID 0 | Reserved for root. |
| GID 1–99 | Reserved for the system and application use. |
| GID 100+ | Allocated for the user’s group. |
To set supplemental IDs when you create a share, run the ibmcloud is share-create command and specify the --initial-owner-gid and --initial-owner-gid properties with the supplemental IDs. See the following
example.
$ ibmcloud is share-create --name my-file-share --zone us-south-2 --profile dp2 --size 1000 --iops 1000 --initial-owner-gid 101 --initial-owner-uid 10001
Creating file share my-file-share under account Test Account as user test.user@ibm.com...
ID r006-bc73917f-b86e-4f6d-b919-6997a88c8031
Name my-file-share
CRN crn:v1:bluemix:public:is:us-south-2:a/a1234567::share:r006-bc73917f-b86e-4f6d-b919-6997a88c8031
Lifecycle state stable
Access control mode security_group
Accessor binding role none
Allowed transit encryption modes none,user_managed
Zone us-south-2
Profile dp2
Size(GB) 1000
IOPS 1000
Encryption provider_managed
Mount Targets ID Name
No mounted targets found.
Resource group ID Name
6edefe513d934fdd872e78ee6a8e73ef defaults
Created 2025-08-01T21:42:38+00:00
Replication role none
Replication status none
Replication status reasons Status code Status message
- -
Snapshot count 0
Snapshot size 0
Source snapshot -
Beta When the IBMCLOUD_IS_FEATURE_SHARE_DENALI_REGIONAL_AVAILABILITY variable is set to true, the same command produces a slightly different response.
$ ibmcloud is share-create --name my-file-share --zone us-south-2 --profile dp2 --size 1000 --iops 1000 --initial-owner-gid 101 --initial-owner-uid 10001
Creating file share my-file-share under account Test Account as user test.user@ibm.com...
ID r006-bc73917f-b86e-4f6d-b919-6997a88c8031
Name my-file-share
CRN crn:v1:bluemix:public:is:us-south-2:a/a1234567::share:r006-bc73917f-b86e-4f6d-b919-6997a88c8031
Lifecycle state pending
Access control mode security_group
Accessor binding role none
Allowed transit encryption modes none,ipsec
Zone us-south-2
Profile dp2
Size(GB) 1000
IOPS 1000
Encryption provider_managed
Mount Targets ID Name
No mounted targets found.
Resource group ID Name
6edefe513d934fdd872e78ee6a8e73ef defaults
Created 2025-08-01T21:42:38+00:00
Replication role none
Replication status none
Replication status reasons Status code Status message
- -
Snapshot count 0
Snapshot size 0
Source snapshot -
Allowed Access Protocols nfs4
Availability Mode zonal
Bandwidth(Mbps) 1
Storage Generation 1
Creating a file share with the API
You can create file shares and mount targets by directly calling the REST APIs.
Before you begin
Set up your API environment. Define variables for the IAM token, API endpoint, and API version. For instructions, see Setting up your API and CLI environment.
You must provide the generation parameter and specify generation=2. For more information, see Generation in the Virtual Private Cloud API reference.
A good way to learn more about the API is to click Get sample API call on the provisioning pages in IBM Cloud console. You can view the correct sequence of API requests and better understand actions and their dependencies.
Creating a mount target for a file share with the API
This request creates or adds a mount target to an existing file share. In this example, the vpc property is specified because the file share's access control mode is vpc. Data encryption in transit cannot be enabled.
Access control modes of the mount target and the share must match. Both must be either vpc or security_group. When you create a mount target with security_group access mode, pay attention to the share's
allowed_transit_encryption_modes. The transit_encryption value must reflect what is allowed for the share.
curl -X POST \
"$vpc_api_endpoint/v1/shares/$share_id/mount_targets?version=2023-08-08&generation=2"\
-H "Authorization: Bearer $iam_token"\
-H 'Content-Type: application/json'\
-d '{
"access_control_mode": "vpc"
"name": "mount-target-name1",
"vpc": {"id": "6e01bc24-4a6e-4a0c-a1bd-4caa0c8159e7"},
"transit_encryption": "none"
}'
A successful response looks like the following example.
{
"access_control_mode": "vpc",
"created_at": "2023-08-08T23:31:59Z",
"href": "https://us-south.iaas.cloud.ibm.com/v1/shares/ff859972-8c39-4528-91df-eb9160eae918/mount_targets/9fdf4438-f5b4-4b6f-8bca-602494fd6c31",
"id": "9fdf4438-f5b4-4b6f-8bca-602494fd6c31",
"lifecycle_state": "pending",
"mount_path": "domain.com:/vol_xyz_2891fd0a_63aa_4deb_9ed5_1159e37cb5aa",
"name": "mount-target-name1",
"resource_type": "share_target",
"transit_encryption": "none",
"vpc": {
"crn": "crn:[...]",
"href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/e6ff7b61-feb4-4c87-94aa-277d6f93e164",
"id": "e6ff7b61-feb4-4c87-94aa-277d6f93e164",
"name": "vpc-name1",
"resource_type": "vpc"
}
}
Adding supplemental IDs when you create a file share with the API
With the API, you can set UID and GID values for the initial_owner property to control access to your file shares. Wherever you mount the file share, the root folder uses that user ID and group ID owner.
You set the UID or GID, or both when you create a share in a POST /shares call.
If you change the supplemental IDs (UID or GID) from the virtual server instance, it is not possible to determine that it was changed. As a result, initial_owner does not change in the API database but changes only in the file
storage system.
Table 1 shows UID and GID values that you can set and values that are reserved.
| ID value | Description |
|---|---|
| UID | |
| UID 0 | Reserved for root. |
| UID 1–99 | Reserved for predefined accounts. |
| UID 100–999 | Reserved by the system for administrative system accounts and groups. |
| UID 1000–10000 | Used by applications account. |
| UID 10000+ | Available for user accounts. |
| GID | |
| GID 0 | Reserved for root. |
| GID 1–99 | Reserved for the system and application use. |
| GID 100+ | Allocated for the user’s group. |
To set supplemental IDs when you create a share, make a POST /shares call and specify the initial_owner property with the supplemental IDs. See the following example.
curl -X POST \
"$vpc_api_endpoint/v1/shares?version=2023-08-08&generation=2"\
-H "Authorization: $iam_token" \
-d '{
"initial_owner": {"gid": 101,"uid": 10001},
"size": 4800,
"name": "share-name",
"profile": {"name": "dp2"},
"zone": {"name": "us-south-1"}
.
.
.
}'
Creating a file share and mount target with Terraform
To use Terraform, download the Terraform CLI and configure the IBM Cloud® Provider plug-in. For more information, see Getting started with Terraform.
VPC infrastructure services use a specific regional endpoint, which targets to us-south by default. If your VPC is created in another region, make sure to target the appropriate region in the provider block in the provider.tf file.
See the following example of targeting a region other than the default us-south.
provider "ibm" {
region = "eu-de"
}
Next steps
Mount your file shares. Mounting is a process by which a server's operating system makes files and directories on the storage device available for users to access through the server's file system. For more information, see the following topics:
- IBM Cloud File Share Mount Helper utility
- Mounting file shares on Red Hat Linux.
- Mounting file shares in CentOS.
- Mounting file shares on Ubuntu.
- Mounting file shares on z/OS
Manage your file shares and data. For more information, see the following topics: