Managing File Systems

In the File Storage service, file systems are associated with a single compartment. When you select a compartment, the Console displays all file systems in the compartment. You can also see exports and snapshots associated with each file system. If there are no file systems in the compartment, see Creating File Systems for instructions about creating one.

The compartment has policies that indicate what actions a user can take to manage file system. UNIX permissions control what actions a user can take on the files stored in the file system. See About Security for more information.

Actions you can take to manage a file system include:

  • Viewing file system details
  • Editing file system settings
  • Viewing associated file system resources
  • Creating an export for the file system
  • Deleting a file system

You can perform most administrative tasks for your file systems using the Console, Command Line Interface (CLI), or API. You can use the Console to list mount targets exporting a specific file system. Use the API or CLI if you want to list all mount targets in a compartment.

To access a file system, it must have at least one export in one mount target. Next, mount the file system from an instance, and then you can create directories and read and write files. For more information about creating an export for a file system, see To create an export for a file system in this topic. For more information about accessing your file system, see Mounting File Systems.

Required IAM Service Policy

To use Oracle Cloud Infrastructure, you must be given the required type of access in a policy  written by an administrator, whether you're using the Console or the REST API with an SDK, CLI, or other tool. If you try to perform an action and get a message that you don’t have permission or are unauthorized, confirm with your administrator the type of access you've been granted and which compartment  you should work in.

For administrators: The policy in Let users create, manage, and delete file systems allows users to manage file systems.

If you're new to policies, see Getting Started with Policies and Common Policies.

Tagging Resources

You can apply tags to your resources to help you organize them according to your business needs. You can apply tags at the time you create a resource, or you can update the resource later with the desired tags. For general information about applying tags, see Resource Tags.

Moving File Systems to a Different Compartment

You can move file systems from one compartment to another. When you move a file system to a new compartment, its associated snapshots move with it. After you move the file system to the new compartment, inherent policies apply immediately and affect access to the file system and snapshots through the Console. Moving these resources doesn't affect access to file systems and snapshots from mounted instances. For more information, see Managing Compartments.

Details About Your File System

The file system details page provides the following information about your file system:

FILE SYSTEM OCID
Every Oracle Cloud Infrastructure resource has an Oracle-assigned unique ID called an Oracle Cloud Identifier (OCID). You need your file system's OCID to use the Command Line Interface (CLI) or the API. You also need the OCID when contacting support. See Resource Identifiers.
Availability Domain
When you create a file system, you specify the availability domain that it resides in. An availability domain is one or more data centers located within a region. You need your file system's availability domain to use the Command Line Interface (CLI) or the API. For more information, see Regions and Availability Domains.
CREATED
The date and time that the file system was created.
COMPARTMENT
When you create a file system, you specify the compartment that it resides in. A compartment is a collection of related resources (such as cloud networks, compute instances, or file systems) that are only accessible to those groups that have been given permission by an administrator in your organization. You need your file system's compartment to use the Command Line Interface (CLI) or the API. For more information, see Managing Compartments.
UTILIZATION
Metered size of the file system that gets updated hourly. For more information, see File System Usage and Metering.
RESOURCES
Resources such as exports and snapshots that are associated with the file system are listed here. Click the resource type link to see a list of each individual resource. Each export in the list shows the file system's export path and mount target. You need the export path to mount a file system.
Warning

Avoid entering confidential information when assigning descriptions, tags, or friendly names to your cloud resources through the Oracle Cloud Infrastructure Console, API, or CLI.

Using the Console

To view file system details

The File Storage service displays a list of file systems in each compartment.

  1. Open the navigation menu. Under Core Infrastructure, click File Storage and then click File Systems.
  2. In the List Scope section, select a compartment.

  3. To view information about a file system, find the file system, click the Actions icon (three dots), and then click View File System Details.

To change the file system name

You can change the display name of the file system.

  1. Open the navigation menu. Under Core Infrastructure, click File Storage and then click File Systems.
  2. In the List Scope section, select a compartment.

  3. To view information about a file system, find the file system, click the Actions icon (three dots), and then click View File System Details.

  4. Click Rename.
  5. Enter the new file system name, and click Rename.
To create an export for a file system

Exports control how NFS clients access file systems when they connect to a mount target. File systems are exported (made available) through mount targets. Each mount target maintains an export set which contains one or many exports. A file system may be exported through one or more mount targets. A file system must have at least one export in one mount target in order for instances to mount the file system. The information used by an export includes the file system OCID, mount target OCID, export set OCID, export path, and client export options. Typically, an export is created in a mount target when the file system is created. Thereafter, you can create additional exports for a file system in any mount target that resides in the same availability domain as the file system.

  1. Open the navigation menu. Under Core Infrastructure, click File Storage and then click File Systems.

  2. In the left-hand navigation, in the List Scope section, under Compartment, select a compartment.
  3. Click the name of the file system you want to create an export for, and click Create Export.

    Note

    File systems are encrypted by default. You cannot turn off encryption.
  4. You can choose to accept the system defaults, or change them by clicking Edit Details.

  5. If you want to accept the defaults for the mount target, click Create. The file system is created with the information displayed. If you want to choose another mount target or change the default information, click the Edit Details link.
  6. In the Mount Target Information section, specify details for the mount target that is associated with the file system:

    • Select an Existing Mount Target: Choose this option if you want to associate the file system with a mount target you already created. Choose the Mount Target from the list. Click the click here link in the dialog box if you want to enable compartment selection for the mount target.

      Tip

      If there aren't any mount targets in the current combination of availability domain and compartment, this option is disabled. You can: 

      • Choose a different compartment.
      • Create a new mount target.
    • Create a New Mount Target: Choose this option if you want to create a new mount target associated with this file system. By default, the mount target is created in your current compartment and you can use network resources in that compartment. Click the click here link in the dialog box if you want to enable compartment selection for the mount target, its VCN, or subnet resources.

      Important

      The mount target is always in the same availability domain as the file system. While it is possible to access mount targets from any AD in a region, for optimal performance, your mount target and file system should be in the same availability domain as the Compute instances that access them. For more information, see Regions and Availability Domains.
    • Create in Compartment: Specify the compartment you want to create the mount target in.
    • New Mount Target Name: Optionally, replace the default with a friendly name for the mount target. It doesn't have to be unique; an Oracle Cloud Identifier (OCID) uniquely identifies the mount target. Avoid entering confidential information.

      Note

      The mount target name is different than the DNS hostname, which is specified in step 7.
    • Virtual Cloud Network Compartment: The compartment containing the cloud network (VCN) in which to create the mount target.
    • Virtual Cloud Network: Select the cloud network (VCN) where you want to create the new mount target.
    • Configure Network Security Groups: Select this option to add this mount target to an NSG you've created. Choose an NSG from the list.

      Important

      Rules for the NSG you select must be configured to allow traffic to the mount target's VNIC using specific protocols and ports. For more information, see Configuring VCN Security Rules for File Storage.
    • Subnet Compartment: Specify the compartment containing a subnet within the VCN to attach the mount target to.
    • Subnet: Select a subnet to attach the mount target to. Subnets can be either AD-specific or regional (regional ones have "regional" after the name). For more information, see VCNs and Subnets.

      Warning

      Each mount target requires three internal IP addresses in the subnet to function. Do not use /30 or smaller subnets for mount target creation because they do not have sufficient available IP addresses. Two of the IP addresses are used during mount target creation. The third IP address must remain available for the mount target to use for high availability failover.
    • Tags:If you have permissions to create a resource, you also have permissions to apply free-form tags to that resource. To apply a defined tag, you must have permissions to use the tag namespace. For more information about tagging, see Resource Tags. If you are not sure if you should apply tags, skip this option (you can apply tags later) or ask your administrator.
  7. Optionally, click Show Advanced Options to configure the mount target's advanced options.

    • IP Address: You can specify an unused IP address in the subnet you selected for the mount target.
    • Hostname: You can specify a hostname you want to assign to the mount target.

      Note

      The File Storage service constructs a fully qualified domain name (FQDN) by combining the hostname with the FQDN of the subnet the mount target is located in.

      For example, myhostname.subnet123.dnslabel.oraclevcn.com.

      Once created, the hostname may be changed in the mount target's Details page. See Managing Mount Targets for more information.

  8. Click Create.

Next, mount the file system from an instance so that you can read and write directories and files in your file system. See Mounting File Systems for instructions about obtaining mount commands for your operating system type and mounting your file system.

To set the file system reported size

The File Storage service reports file system capacity as 8589934592 gibibytes (GiB) and 8589934592 gibiinodes (GiI) by default. Sometimes, application installers perform a space requirement check prior to running an installation process but cannot correctly interpret the reported size or reported inodes of the file system. When this occurs, you can define the file system size reported to the operating system by setting the Reported Size or Reported Inodes value in the file system's mount target. Typically, setting the size to 1024 GiB and the inodes to 1024 GiI permits successful installation.

Important

Changing the Reported Size or Reported Inodes for a mount target affects all file systems exported by the mount target. Changing these values does not limit the amount of data you can store.
  1. Open the navigation menu. Under Core Infrastructure, click File Storage and then click File Systems.
  2. In the List Scope section, select a compartment.

  3. Find the mount target you're interested in, click the Actions icon (three dots), and then click View File System Details.
  4. In Exports, click on the mount target name.
  5. Click the Reported Size (in GiB) Edit or the Reported Inodes (in Gil) icon.
  6. Enter the maximum free space in gibibytes or the maximum inodes in gibinodes you want the File Storage service to report.
  7. Click the Save icon.
Important

There can be a delay of up to 1 hour when reporting file system usage, either in the console or by using the df command. For more information, see File System Usage and Metering.
To manage tags for a file system
  1. Open the navigation menu. Under Core Infrastructure, click File Storage and then click File Systems.
  2. In the List Scope section, select a compartment.

  3. Find the file system you're interested in, click the Actions icon (three dots), and then click View File System Details.

  4. Click the Tags tab to view or edit the existing tags. Or click Apply tag(s) to add new ones.

For more information, see Resource Tags.

To move a file system to a different compartment
  1. Open the Console,
  2. Open the navigation menu. Under Core Infrastructure, click File Storage and then click File Systems.
  3. In the List Scope section, select a compartment.
  4. Find the file system in the list, click the the Actions icon (three dots), and then click Change Compartment.
  5. Choose the destination compartment from the list.
  6. Click Change Compartment.

The file system is moved immediately. Moving a file system doesn't affect mounted instances.

To move a file system to a different subnet

There might be situations where you need to move a file system to a different subnet. For example, since you can't change subnet size, you might need to move the file system to a larger or smaller subnet as your needs change.

  1. Create the new subnet. See VCNs and Subnets for instructions.
  2. Create a new mount target in the new subnet. See To create a mount target for instructions.
  3. Create new export with the same export path in the new mount target to the file system. See To create an export for a file system for instructions.

    • Choose Select Existing Mount Target
    • Be sure that the export path for the new export is exactly the same as the export path for the original export. The original and new mount target can exist at the same time without issue.
  4. Switch over the instance mount point to the new mount target. This can be done at any time convenient to your maintenance schedule:
    1. Stop any workload application processes running on the instance mount point.
    2. Unmount the file system. See To unmount a file system for instructions.
    3. Mount the file system using the new mount target, but the same mount point that was previously used.

      For example: If the file system was mounted with the original mount target like this:

      sudo mount 10.0.0.10:/my-export-path /mnt/MyMountPoint

      Then the new mount command would look like this:

      sudo mount 10.1.1.10:/my-export-path /mnt/MyMountPoint

      See Mounting File Systems for instructions.

    4. Update any system configuration files that use the old export path. For example, /etc/fstab.
    5. Start workload applications and verify that they can access the file system as expected.
    6. After testing and verification is complete, you can delete the original mount target and subnet.
To assign a key to a file system

File systems use Oracle-managed keys by default, which leaves all encryption-related matters to Oracle. Optionally, you can encrypt the data in this file system using your own Vault encryption key.

Warning

Besure to back up your vaults and keys. Deleting a vault and key otherwise means losing the ability to decrypt any resource or data that the key was used to encrypt. For more information, see Backing Up Vaults and Keys.

Prerequisites:

  • At least one key vault and key in the Vault service. For more information, see Overview of Vault.
  • Correctly set permissions that allow the File Storage service to use keys. For example:

    Allow service FssOc1Prod to use keys in compartment <compartment_name>

    For more information, see Common Policies.

  1. Open the navigation menu. Under Core Infrastructure, click File Storage and then click File Systems.
  2. Under List Scope, in the Compartment list, choose the compartment that contains the file system that you want to encrypt with a Vault master encryption key.
  3. From the list of file systems, click the file system name.
  4. Next to Encryption Key, click Edit.

  5. In Encryption Type, select Encrypt using customer-managed keys.
  6. Choose the vault compartment, vault, key compartment, and key.

  7. When you are finished, click Save Changes.

To specify Oracle-managed keys for a file system

File systems use Oracle-managed keys by default, which leaves all encryption-related matters to Oracle. However, if you assign a Vault key to a file system, you can later return the file system to using Oracle-managed keys for encryption. For more information, see Overview of Vault.

  1. Open the navigation menu. Under Core Infrastructure, click File Storage and then click File Systems.
  2. Under List Scope, in the Compartment list, choose the compartment that contains the file system that you want to encrypt with a Vault master encryption key.
  3. From the list of file systems, click the file system name.
  4. Next to Encryption Key, click Edit.

  5. In Encryption Type, select Encrypt using Oracle-managed keys.
  6. When you are finished, click Save Changes.

To delete a file system

You can permanently delete a file system.

Warning

You cannot undo this operation. Any data in a file system is permanently deleted with the file system. Snapshots of the file system are permanently deleted with the file system. You cannot recover a deleted file system or its snapshots.
  1. Open the navigation menu. Under Core Infrastructure, click File Storage and then click File Systems.
  2. In the List Scope section, select a compartment.

  3. Find the file system you want to delete.
  4. Click the Actions icon (three dots), and then click View File System Details.
  5. Delete all of the file system's exports:

    • In Exports, select the check box for all exports listed, and then click Delete.
  6. When all of the exports are deleted, click Delete to delete the file system.

The file system is deleted immediately, along with all of its snapshots.

Using the Command Line Interface (CLI)

For information about using the CLI, see Command Line Interface (CLI).

To list file systems

Open a command prompt and run oci fs file-system list to list all the file systems in a specified availability domain and compartment.

For example:

oci fs file-system list --availability-domain <target_availability_domain> --compartment-id <target_compartment_id>
To get a specific file system

Open a command prompt and run oci fs file-system get to retrieve information about a specific file system.

For example:

oci fs file-system get --file-system-id <file_system_OCID>
To update a file system

Open a command prompt and run oci fs file-system update to update a specific file system's information.

For example:

oci fs file-system update --file-system-id <file_system_OCID> --display-name "<New File System Name>"
Warning

Avoid entering confidential information in the file system display-name.
To create an export for a file system

Exports control how NFS clients access file systems when they connect to a mount target. File systems are exported (made available) through mount targets. Each mount target maintains an export set which contains one or many exports. A file system may be exported through one or more mount targets. A file system must have at least one export in one mount target in order for instances to mount the file system. The information used by an export includes the file system OCID, mount target OCID, export set OCID, export path, and client export options.Typically, an export is created in a mount target when the file system is created. Thereafter, you can create additional exports for a file system in any mount target that resides in the same availability domain as the file system.

Open a command prompt and run oci fs export create to create an export for a specified file system within a specified export set.

For example:

oci fs export create --export-set-id <export_set_OCID> --file-system-id <file_system_OCID> --path "</pathname>"
Important

The export path must start with a slash (/) followed by a sequence of zero or more slash-separated elements. For multiple file systems associated with a single mount target, the export path sequence for the first file system cannot contain the complete path element sequence of the second file system export path sequence. Export paths cannot end in a slash. No export path element can be a period (.) or two periods in sequence (..). Lastly, no export path can exceed 255 bytes. For example:

Acceptable:

/example and /path

/example and /example2

Not Acceptable:

/example and /example/path

/ and /example

/example/

/example/path/../example1

Warning

If one file system associated to a mount target has '/' specified as an export path, you can't associate another file system with that mount target.
Note

Export paths cannot be edited after the export is created. If you want to use a different export path, you must create a new export with the desired path. Optionally, you can then delete the export with the old path.

For more information, see Paths in File Systems.

To set the file system reported free space

Some existing application installers perform a capacity check before running an installation process. Sometimes an installation fails because of too much available capacity. The File Storage service currently reports 8 exabytes of available capacity by default for each file system.

Customers can define how much free capacity is reported as available to the operating system.

Open a command prompt and type in the following command:

oci fs export-set update --export-set-id <export_set_ OCID> --max-fs-stat-bytes <number_of_bytes>
Important

The maximum free space setting affects each export in the export set. Setting the maximum free space does not limit the amount of data you can store.
To move a file system to a different compartment

oci fs file-system change-file-system-compartment --file-system-id <file_system_OCID> --compartment-id <destination_compartment_OCID>
To update the key for a file system

File systems use Oracle-managed keys by default, which leaves all encryption-related matters to Oracle. Optionally, you can encrypt the data in this file system using your own Vault encryption key.

Warning

Besure to back up your vaults and keys. Deleting a vault and key otherwise means losing the ability to decrypt any resource or data that the key was used to encrypt. For more information, see Backing Up Vaults and Keys.

Prerequisites:

  • At least one key vault and key in the Vault service. For more information, see Overview of Vault.
  • Correctly set permissions that allow the File Storage service to use keys. For example:

    Allow service FssOc1Prod to use keys in compartment <compartment_name>

    For more information, see Common Policies.

Open a command prompt and run oci fs file-system update to update the file system with a new key.

oci fs file-system update --file-system-id <file_system_OCID> --kms-key-id <target_key_id>

For example:

oci fs file-system update --file-system-id ocid1.filesystem.oc1.phx.<unique_id> --kms-key-id ocid1.key.oc1.phx.<unique_id>
To specify Oracle-managed keys for a file system

File systems use Oracle-managed keys by default, which leaves all encryption-related matters to Oracle. However, if you assign a Vault key to a file system, you can later return the file system to using Oracle-managed keys for encryption.

Open a command prompt and run oci fs file-system update. Leave the --kms-key-id value unspecified.

oci fs file-system update --file-system-id <file_system_OCID> --kms-key-id ""

For example:

oci fs file-system update --file-system-id ocid1.filesystem.oc1.phx.<unique_id> --kms-key-id ""
To delete a file system

You can delete a file system if no non-deleted export resources reference it. Deleting a file system also deletes all its snapshots.

Open a command prompt and run oci fs file-system delete to delete a file system.

For example:

oci fs file-system delete --file-system-id <file_system_OCID>
Warning

You cannot undo this operation. Any data in a file system is permanently deleted with the file system. Snapshots of the file system are permanently deleted with the file system. You cannot recover a deleted file system or its snapshots.