Managing File Systems

A Storage Gateway file system connects a directory on a local host to an Object Storage bucket in Oracle Cloud Infrastructure. This topic describes how to manage Storage Gateway file systems.

Adding a File System

You can add file systems in Storage Gateway and connect each file system to an Object Storage bucket in your tenancy.

To add a file system
  1. Log in to the management console.
  2. Click File Systems on the upper-right area of the management console.
  3. Click Create File System.
  4. Enter the required information in Create a File System:

    • File System Name: A unique, friendly name for the file system. Avoid entering confidential information. Use the following guidelines when naming a file system:

      • Use from 1 to 256 characters.
      • Valid characters are letters (upper or lower case), numbers, hyphens, underscores, and periods.

      Important

      The name cannot contain the following:

      • A slash (/) character because this character delimits bucket and object names in Oracle Cloud Infrastructure Object Storage
      • The strings "pub" or "priv"

      If an Object Storage bucket by this file system name doesn’t exist in your tenancy, the bucket is created.

      If a corresponding Object Storage bucket by this file system name exists in your tenancy and there is data in the bucket, Storage Gateway works asynchronously to sync the bucket and file system contents.

    • Select the Object Storage tier in which you want to store your data
      Important

      Once set, you cannot change the storage tier in which a bucket resides.

      You can use the Oracle Cloud Infrastructure Object Storage object lifecycle policies feature to manage the archiving and deletion of objects in a bucket according to a predefined schedule. See Using Object Lifecycle Management for details.

      • Standard: The Standard tier is the primary default Object Storage tier for storing data that requires frequent and fast access. See Overview of Object Storage for more information.
      • Archive: The Archive tier is a special tier for storing data that is accessed infrequently and requires long retention periods. See Overview of Archive Storage for more information. Access to data in the Archive tier is not immediate since you must restore archived data before it’s accessible (see Restoring Files and Objects from Archive Storage).
    • Object Storage endpoint: Required. The Object Storage API endpoint for your service instance. To find the object storage API endpoint for your Oracle Cloud Infrastructure Object Storage tenancy, see the API documentation for Oracle Cloud Infrastructure Object Storage.

      Important

      The following information is required to connect your Storage Gateway file systems to Oracle Cloud Infrastructure. See Required Keys and OCIDs for detailed information on how to generate the required keys and where to obtain these OCIDs.
    • Compartment OCID: Required. Unique identifier of your Oracle Cloud Infrastructure Object Storage compartment.
    • Tenant OCID: Required. Unique identifier of your Oracle Cloud Infrastructure Object Storage tenancy.
    • User OCID: Required. Unique identifier of your Oracle Cloud Infrastructure Object Storage user.
    • Public Key's Finger Print: Required. Your Oracle Cloud Infrastructure Object Storage public key fingerprint.
    • Private Key: Required. Your Oracle Cloud Infrastructure Object Storage private key.
    • Private Key Passphrase: Required if a passphrase was specified during key creation. Your Oracle Cloud Infrastructure Object Storage private key passphrase.

      Note

      Your private key and passphrase are securely stored in the Storage Gateway docker. The Storage Gateway installation generates a pair of public and private keys. The system uses the public key to encrypt sensitive data.
  5. Click Save.

    The values you entered must match your Oracle Cloud Infrastructure credentials. If you get an error message, verify your entries, update any incorrect values, and click Save again.

  6. Click Show Advanced File System Configuration.

    Enter the required configuration information or click Use Default to accept the default values:

    • NFS Allowed Hosts: A comma-separated list of hosts allowed to connect to the NFS export. You can also specify * to allow all hosts to connect.

      For example: 2001:db8:9:e54::/64, 192.0.2.0/24

    • NFS Export Options: The NFS export options.

      Example: rw, sync, insecure, no_subtree_check, no_root_squash

      Important

      Do not specify the fsid option.
    • Concurrent Uploads: The number of concurrent uploads to Oracle Cloud Infrastructure.

      This field indicates the maximum number of files that can be concurrently uploaded in Storage Gateway. If the value is 15, the concurrent file uploads can be between 1-15.

      The allowed range is from 1 to 30.

    • Sync Policy: The metadata operations are flushed to the disk based on the sync policy, but do not affect on-disk consistency. Currently, only Posix Standard is supported. Only the synchronous transactions (like fsync, ODSYNC, and OSYNC) are committed to the disk. All other transactions are handled asynchronously.
    • Cloud Read-ahead: The number of blocks to be downloaded and used to read ahead when reading files for improved performance.

      Default value: 50

    • Maximum Read Cache Size in GiB: The maximum read cache.

      When the read cache is full or reaches the configured limit, Storage Gateway removes files from the cache based on a least recently used (LRU) algorithm. Files pending upload to your tenancy are not removed from cache. You can also preserve files that you do not want removed from cache.

      Note

      The number of files in cache is limited to 20,000, regardless of the specified cache size in bytes.

      See Configuring the Cache for File Systems for details.

      The default value depends on how you provisioned local storage before installing Storage Gateway. The recommended local storage disk size is 600 GB (500 GB for file system cache, 80 GB for metadata, 20 GB for log). If you followed the documented recommendations, the default value for the read cache is approximately 300 GB.

  7. Click Save.

    The file system is created and appears in the File Systems listing.

Connecting a File System

After you create a file system, you must connect the file system to an Oracle Cloud Infrastructure Object Storage bucket before you can store and retrieve data through the file system.

Caution

If network connectivity with Oracle Cloud Infrastructure is lost, your file system is disconnected.
To connect a file system
  1. Log in to the Storage Gateway management console.
  2. On the Dashboard tab, identify the file system that you want to connect to your Object Storage bucket.
  3. Click Connect.

    If a bucket with the same name as the file system exists in Object Storage, the file system is connected to that bucket. Any existing data cached in the Storage Gateway file system is deleted to ensure consistency with the data stored in the bucket. If a bucket by that name doesn’t exist, the bucket is created and the file system is connected to the bucket. If the compartment OCID was specified during file system creation, then the bucket is created in that compartment. Otherwise, the bucket is created in the root compartment by default.
    Important

    You can mount a read/write file system on only one Storage Gateway at a time.

    If the file system that you're importing is connected to another Storage Gateway, the File System: Claim Ownership window appears. You can claim ownership and confirm that the other Storage Gateway can be disconnected. Enter the following information, and then click Claim Ownership:
    • Public key finger print
    • Private key
    • Private key passphrase

    Claiming ownership ensures that you don't inadvertently connect a new file system to a bucket that's already connected to another Storage Gateway file system.

Mounting File Systems on Clients

Each Storage Gateway file system maps a directory to an Oracle Cloud Infrastructure Object Storage bucket. To establish the connection between Storage Gateway and an NFS client, you must mount the Storage Gateway file system on the NFS client.

Any Linux/UNIX NFS client certified to work with NFSv4 server running on Oracle Linux 7.x is compatible with Storage Gateway.

Note

Storage Gateway does not currently support NFS clients running on Windows or Mac OS.
To mount a Storage Gateway file system
  1. Log in to the Storage Gateway host.
  2. Start Storage Gateway:

    sudo ocisg up
  3. Find the NFS port number:

    sudo ocisg info

    Note the NFS port number from the output. For example:

    Management Console: https://myStorageGatewayHost.example.com:32775
    
    If you have already configured a OCISG File System via the Management Console, you can access the NFS share using the following port.
    
    NFS Port: 32774
    
    Example: mount -t nfs -o vers=4,port=32774 myStorageGatewayHost.example.com:/<OCISG File System name> /local_mount_point

    In the sample output:

    • myStorageGatewayHost.example.com is the Storage Gateway host name.
    • 32775 is the management console port number.
    • 32774 is the NFS port number.
  4. Log in to the NFS client from which you want to access your service instance through Storage Gateway.
  5. Create a directory on the NFS client.
  6. Mount the file system on the directory that you created on the NFS client:

    sudo mount -t nfs -o vers=4,port=<NFS_port_number> <storage_gateway_host_name>:/<ocisg_file system_name> /<local_mount_point>

    In this command:

    • Replace <NFS_port_number> with the NFS port number you noted earlier.
    • Replace <storage_gateway_host_name> with the server name or IP address of the server on which Storage Gateway is installed.
    • Replace <ocisg_file system_name> with the file system name that you want to mount.
    • Replace <local_mount_point> with the path to the directory you created on the NFS client.

    For example:

    sudo mount -t nfs -o vers=4,port=32774 myStorageGatewayHost.example.com:/myFirstFS /home/xyz/abc

    In this example,

    • 32774 is the NFS port.
    • myStorageGatewayHost.example.com is the Storage Gateway host name.
    • myFirstFS is the file system name.
    • /home/xyz/abc is the path to the directory abc on the NFS client.

The Storage Gateway file system is now mounted on the NFS client directory. You can now access the Storage Gateway file system from the NFS client.

For more information, see Using Storage Gateway File Management Operations.

To mount a Storage Gateway file system automatically after a reboot

You can mount a Storage Gateway NFS share either on directly to the host or remotely. When Storage Gateway restarts, the mount point may encounter residual file handle issues depending on the readiness of the fuse mount. The fuse mount takes some time to be available for a Storage Gateway restart.

Using an /etc/fstab entry to automount a Storage Gateway file system is not supported. Instead, you can set up an optional cron job for this purpose.

The cron job ensures the NFS share to be mounted only when the fuse mount is ready. However, this solution only works when the mount point is on the same Storage Gateway host. You must remount the NFS share to address file handling issues if it is mounted remotely.

  1. Log in to the Storage Gateway host.
  2. Create an executable script called mountSgFilesystem.sh and save it to an accessible location:

    #!/bin/sh
    #$1 - ip address
    #$2 - nfs port
    #$3 - SG filesystem name
    #$4 - local mountpoint
    
    for n in $(seq 1 20)
    do
    fs=$(docker exec ocisg cat /etc/exports | grep "$3")
    if [ ! -z "$fs" ]; then
    sleep 1
    mount -t nfs -o vers=4,port=$2 $1:/$3 $4
    break
    fi
    sleep 30
    done
  3. Create a cron job that runs only after boot up:

    crontab -e
    @reboot sleep 60 && /<path_of_script>/mountSgFilesystem.sh <ip_address> <nfs_port> <SG_filesystem_name> <local_nfs_mount_point>

Viewing the Details of a File System

You can view the configuration details of a file system and monitor the upload activity through the management console of Storage Gateway.

To view the details of a file system
  1. Log in to the management console.
  2. Click the name of the file system.

    • The Details tab displays the Oracle Cloud Infrastructure service type, storage tier, and the identity domain associated with your tenancy. If the file system is connected, you can see mount point connection information to help you with mounting that file system. For example:

      NFS Client Mount Command: mount -t nfs -o vers=4,port=<nfs_mount_port> 129.213.122.84:/perftest01 /<local_mount_point>

    • The Settings tab displays the following details:

      • Details of the tenancy and scope specified for the file system.
      • File system properties.
      • NFS and cache settings for the file system.

      You can edit these settings. If you make changes, remember to click Save.

      If your file system is connected, you can also see:

    • The Activity tab, which shows ongoing and pending file upload activity.

      If you contact Oracle Support Services about any issue with the file system, you might need to provide the file system log to help diagnose the issue. To view or download the file system log, click View Streaming Logs near the lower-right corner of the Details tab.

    • The Completed Uploads tab, which shows the last 100 files that were uploaded to Oracle Cloud Infrastructure Object Storage during the current browser session.

      Note

      The file list doesn’t persist across browser sessions. If you refresh the page or open the Completed Uploads tab in another browser after the files are uploaded, the list will be empty.
    • You can also disconnect the file system. See Disconnecting a File System.

Changing the Properties of a File System

You can change the properties of a file system using the Storage Gateway management console.

To change the properties of a file system
  1. Log in to the management console.
  2. In the Dashboard, click the name of the file system that you want to edit.
  3. In the Settings tab, edit the file system properties and advanced settings, such as the cache limits.
  4. Click Save.
  5. For the changes to take effect, disconnect and reconnect the file system.

Refreshing a File System

The auto-refresh feature triggers file system refreshes based on a time interval you specify. The system schedules the next refresh after any in-progress refresh completes. That means the elapsed time between the beginning of any two successive refreshes is equal to the specified auto-refresh interval plus the time required to run a file system refresh.

Note

Storage Gateway enables asynchronous movement of data to and from Object Storage. The Storage Gateway product currently cannot make commitments as to when files can be synced from an Object Storage bucket to the Storage Gateway NFS mount.

When an aggressive refresh interval is set that refreshes only occur when in-progress refreshes finish, so there will typically be a lag between contents of the Storage Gateway NFS mount and Object Storage bucket. As the volume of objects in the bucket grows the refresh time will start to increase.

Use the following command to configure the auto-refresh feature:

ocisg set <file_system_name> dataset.refreshInterval=<interval_in_minutes>

The configuration command works on created and connected file systems. The configuration does not take effect until the file system is disconnected and reconnected or the Storage Gateway application restarts. To apply the changes, run:

ocisg down
ocisg up

Attribute caching can cause NFS clients to be unaware of files, corresponding to new objects in the bucket, that are created in a Storage Gateway file system during a refresh. You can use the noac mount option to turn off attribute caching. Turning off attribute caching can affect system performance.

When you run a refresh, the system reads attributes and fetches information about all objects in the corresponding bucket. Use a larger refresh interval for buckets with many objects.

Note

After you refresh a file system, or create one for a bucket that already contains objects, Oracle recommends that you check for any files that might have been missed due to network connectivity issues.

To check for missing files, run the following command:

zgrep -ni "failed to get the object for" <path_to_gateway_logs>/<file_system_name>.*

For example, if the path to the gateway logging directory is /ocisg/log and the file system name is my-fs-1, the command is:

zgrep -ni "failed to get the object for" /ocisg/log/my-fs-1.*

Files listed in the output of this command were not successfully registered with the gateway. If any file names appear in the list, refresh the file system again.

Disconnecting a File System

When a file system is disconnected, no one can access or modify that file system.

We recommend disconnecting file systems that are not in use. Disconnecting a file system frees up the resources associated with that file system, making those resources available to file systems that are active (connected).

To disconnect a file system
  1. Log in to the management console.
  2. In the Dashboard, click the name of the file system that you want to disconnect.
  3. Click Disconnect.

    When you disconnect a file system, the bucket to which the file system was previously connected and the contents of that bucket remain intact.

  4. For the changes to take effect, disconnect and reconnect the file system.

You can resume storing and retrieving data by connecting the file system again. You can delete the disconnected file system when you no longer need it. For more information, see Deleting a File System.

Importing an Existing File System

Before you import an existing file system from another Storage Gateway, ensure that any pending file uploads to Oracle Cloud Infrastructure Object Storage are complete.

To import an existing file system
  1. Log in to the management console.
  2. Click the Create File System navigation link.
  3. Click Create File System in the navigation pane on the left.

    The Create a File System page appears.

  4. Enter the required information in Create a File System.

    For the file system name, enter the name of the existing file system that you want to import to this Storage Gateway.

  5. Click Save.
  6. Select the options that you’d like to enable in the file system.
  7. Click Show Advanced and enter the required information.
  8. Click Save.

    The file system is created and appears on the Dashboard tab.

  9. Click Connect for the file system that you want to import.

    1. If the file system that you're importing is connected to another Storage Gateway, the File System: Claim Ownership window appears so you can claim ownership and confirm that the other Storage Gateway can be disconnected. Enter the following information and click Claim Ownership:

      • Public key finger print
      • Private key
      • Private key passphrase
    2. If you connect to a file system that previously belonged to a different gateway, you must restart the new owning gateway:

      ocisg down
      ocisg up
  10. Mount the file system to a directory on the Storage Gateway host and set up the NFS export. For example:

    sudo mount -t nfs -o vers=4,port=<NFS_port_number> <storage_gateway_host_name>:/<ocisg_file system_name> /<local_mount_point>

    In this command:

    • Replace <NFS_port_number> with the NFS port number you noted earlier.
    • Replace <storage_gateway_host_name> with the server name or IP address of the server on which Storage Gateway is installed.
    • Replace <ocisg_file system_name> with the file system name that you want to mount.
    • Replace <local_mount_point> with the path to the directory you created on the NFS client.

Deleting a File System

You can delete a file system from Storage Gateway when you no longer need it.

To delete a file system:
  1. Log in to the management console.
  2. On the Dashboard, identify the file system that you want to delete.

    Important

    When you disconnect a file system, the bucket to which the file system was previously connected and the contents of that bucket remain intact.

    Deleting a file system does not automatically delete the objects in the bucket. If you want to remove objects from the Object Storage bucket, set the Delete Old File Versions property for the file system and delete all the files before disconnecting the file system.

  3. Ensure that the file system is disconnected. If it’s still connected, click Disconnect.

  4. After the file system is disconnected, click its name.

    The details of the file system appear.

  5. Click Delete.

    The file system is deleted from Storage Gateway.