File Storage Overview

9 File Storage Overview

The File Storage service provides a durable, scalable, secure, enterprise-grade network file system.

The File Storage service supports these protocols:

Network File System version 4.1 (NFSv4.1)
Network File System version 4.0 (NFSv4)
Network File System version 3.0 (NFSv3)
Server Message Block (SMBv2 - SMBv3.1) – Requires Active Directory

For step-by-step instructions for managing File Storage, refer to File System Storage in the Oracle Private Cloud Appliance User Guide.

File Storage Connectivity

You can connect to a File Storage service file system from any instance in your Virtual Cloud Network (VCN).

Suitable Workloads

The File Storage service is designed to meet the needs of applications and users that need an enterprise file system across a wide range of use cases, including the following:

General Purpose File Storage: Access to a pool of file systems to manage growth of structured and unstructured data.
Big Data and Analytics: Run analytic workloads and use shared file systems to store persistent data.
Lift and Shift of Enterprise Applications: Migrate existing Oracle applications that need NFS storage, such as Oracle E-Business Suite and PeopleSoft.
Databases and Transactional Applications: Run test and development workloads with Oracle, MySQL, or other databases.
Backups, Business Continuity, and Disaster Recovery: Host a secondary copy of relevant file systems from on premises to the cloud for backup and disaster recovery purposes.
Portable Operating System Interface (POSIX)-compliant file system
MicroServices and Docker: Deliver stateful persistence for containers. Easily scale as your container-based environments grow.

Data Protection with Snapshots

The File Storage service supports snapshots for data protection of your file system. Snapshots are a consistent, point-in-time view of your file systems. Snapshots are copy-on-write, and scoped to the entire file system. The File Storage service encrypts all file system and snapshot data at rest. You can take as many snapshots as you need.

For data protection, you can use a tool that supports NFS to copy your data to a different file system, object storage, or remote location.

For best performance, use the parallel tar (partar) and parallel copy (parcp) tools provided in the File Storage Parallel File Toolkit for this purpose. These tools work best with parallel workloads and requests. The Parallel File Toolkit is available for Oracle Linux, Red Hat Enterprise Linux, and CentOS. You can use rsync or regular tar for other operating system types. See Installing the Parallel File Tools for more information.

File Storage Objects

Mount Target

A mount target is an NFS endpoint in a subnet of your choice. The mount target provides the IP address that is used in the mount command when connecting NFS clients to a file system. File systems are exported (made available) through mount targets.

For an instance to mount a file system, the instance's Virtual Cloud Network (VCN) must have a mount target. A VCN can only have one mount target.

You can reuse the same mount target to make many file systems available. To reuse the same mount target for multiple file systems, create an export in the mount target for each file system.

Export

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 must have at least one export in one mount target for compute instances to mount the file system.

Export Set

An export set is a collection of one or more exports that control what file systems the mount target exports and how those file systems are found using the NFS mount protocol. Each mount target has an export set. Each file system associated with the mount target has at least one export in the export set.

Export Path

The export path uniquely identifies the file system within the mount target. The export path is used by a compute instance to mount (logically attach to) the file system. For more information, see File Storage Paths.

Export Options

NFS export options are a set of parameters within the export that specify the level of access granted to NFS clients when they connect to a mount target. An NFS export options entry within an export defines access for a single IP address or CIDR block range.

File System

In Private Cloud Appliance, file system refers to a file system that is accessed by one or more clients over the network. File systems are associated with a single compartment. File systems must have at least one export in one mount target for any client to mount and use the file system. Data is added to a file system from the client that has mounted (has access to) the file system.

The total number of file systems is limited to 100 per tenancy.

Virtual Cloud Network (VCN)

A private network that you set up in the Private Cloud Appliance, with firewall rules and specific types of communication gateways that you can choose to use. A VCN covers a single, contiguous IPv4 CIDR block of your choice.

Subnet

Subnets are subdivisions you define in a VCN (for example, 10.0.0.0/24 and 10.0.1.0/24). Subnets contain virtual network interface cards (VNICs), which attach to compute instances. A subnet consists of a contiguous range of IP addresses that do not overlap with other subnets in the VCN.

Security Rules

Security rules are virtual firewall rules for your VCN. Your VCN comes with a default security list, and you can add more. These security lists provide ingress and egress rules that specify the types of traffic allowed in and out of the compute instances. You can choose whether a given rule is stateful or stateless. Security list rules must be set up so that clients can connect to file system mount targets.

Another method for applying security rules is to set them up in a network security group (NSG), and then add the mount target to the NSG. Unlike security list rules that apply to all VNICs in the subnet, NSGs apply only to resource VNICs you add to the NSG.

Snapshots

Snapshots provide a consistent, point-in-time view of your file system, and you can take as many snapshots as you need. Each snapshot reflects only data that changed from the previous snapshot.

File Storage Paths

The File Storage service uses these kinds of paths:

Export Paths are part of the information contained in an export that makes a file system available through a mount target.

The export path is automatically generated when you create an export, and it uniquely identifies the file system within the mount target.

Note – When you create an export from the CLI, you must specify a --path <path> argument. The path you specify is recorded but not used for mounting file systems. The appliance auto-generates a path that is used to mount the file system.

Export path syntax:
```
/export/<file-system-OCID-unique-string>
                     
```
where:
- /export/ – Is the beginning of the export path.
- <file-system-OCID-unique-string> – Is the unique character string portion of the file system's OCID.
For example, a file system with this OCID . . .
```
ocid1.filesystem.oc1.pca.d0v812zdp48onybubehhx1c67i4p3mjfth5avt3z2rkn50uqpbce3fhsa8nm
```
. . . has an export path that looks like this:
```
/export/d0v812zdp48onybubehhx1c67i4p3mjfth5avt3z2rkn50uqpbce3fhsa8nm
```
The export path is used by a file system client to mount (logically attach to) the file system. This path is unrelated to any path within the file system or the client instance. It exists solely as a way to distinguish one file system from another within a single mount target.

Example of an export path in a client's mount command:
```
sudo mount -t nfs  \
 -o nfsvers=4.0 192.0.2.0:/export/d0v812zdp48onybubehhx1c67i4p3mjfth5avt3z2rkn50uqpbce3fhsa8nm /mnt/fs
```
In this mount command example, 192.0.2.0 is the mount target IP address./export/d0v812zdp48onybubehhx1c67i4p3mjfth5avt3z2rkn50uqpbce3fhsa8nm is the unique export path that was specified when the file system was associated with a mount target during creation.

Export paths cannot be edited after the export is created.

For more information about export paths and mounting file systems, refer to the File System Storage in the Oracle Private Cloud Appliance User Guide.
Mount Point Paths are paths within a client instance to a locally accessible directory to which the remote file system is mounted.

In this mount command example, /mnt/fs is the path to the directory on the client instance on which the external file system is mounted.
```
sudo mount -t nfs  \
 -o nfsvers=4.0 192.0.2.0:/export/d0v812zdp48onybubehhx1c67i4p3mjfth5avt3z2rkn50uqpbce3fhsa8nm /mnt/fs
```
File System Paths are paths to directories within the file system, and contain the contents of the file system. When the file system is mounted, you can create any directory structure within it.

VCN Security Rules for File Storage

Before you can mount a file system, you must configure security rules to allow traffic to the mount target's VNIC using specific protocols and ports. Security rules enable traffic for the following:

Open Network Computing Remote Procedure Call (ONC RPC) rpcbind utility protocol
Network File System (NFS) protocol
Network File System (MOUNT) protocol
Network Lock Manager (NLM) protocol

Ways to Enable Security Rules for File Storage

The Networking service offers two virtual firewall features that both use security rules to control traffic at the packet level. The two features are:

Security lists: The original virtual firewall feature from the Networking service. When you create a VCN, a default security list is also created. Add the required rules to the security list for the subnet that contains the mount target.
Network security groups (NSGs): A subsequent feature designed for application components that have different security postures. Create an NSG that contains the required rules, and then add the mount target to the NSG. Each mount target can belong to up to five (5) NSGs.

Important:

You can use security lists alone, network security groups alone, or both together. It depends on your particular security needs.

If you choose to use both security lists and network security groups, the set of rules that applies to a given mount target VNIC is the combination of these items:

The security rules in the security lists associated with the VNIC's subnet
The security rules in all NSGs that the VNIC is in

It doesn't matter which method you use to apply security rules to the mount target VNIC, as long as the ports for protocols necessary for File Storage are correctly configured in the rules applied.

For additional conceptual information, see Virtual Firewall.

For instructions on how to create security rules and NSGs for the File Storage service, refer to the section titled Controlling Access to File Storage in the File System Storage chapter in the Oracle Private Cloud Appliance User Guide.

For general instructions for creating security lists and NSGs, refer to the sections titled Controlling Traffic with Security Lists and Controlling Traffic with Network Security Groups in the Networking chapter in the Oracle Private Cloud Appliance User Guide.

File Storage Network Ports

This table lists the port numbers used for networking services that support File Storage.

When you configure security lists and network security groups for the File Storage service, use the port numbers for the particular service you are using. For example, for NFS configure ports 2048–2050 for TCP and UDP.

Service	Protocol	Port
RPC	TCP, UDP	111
NFS	TCP, UDP	2048, 2049, 2050
lockd	TCP, UDP	4045
mountd	TCP, UDP	20048
SMB	TCP, UDP	445
LDAP	TCP, UDP	389
Kerberos	TCP, UDP	88
DNS	TCP, UDP	53

Export Options for File Storage

NFS export options enable you to create more granular access control than is possible using security list rules to limit VCN access. You can use NFS export options to specify access levels for IP addresses or CIDR blocks connecting to file systems through exports in a mount target. Access can be restricted so that each client’s file system is inaccessible and invisible to the other, providing better security controls in multi-tenant environments.

Using NFS export option access controls, you can limit clients' ability to connect to the file system and view or write data. For example, if you want to allow clients to consume but not update resources in your file system, you can set access to read-only. You can also reduce client root access to your file systems and map specified User IDs (UIDs) and Group IDs (GIDs) to a single anonymous UID/GID of your choice.

Export Options

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 separate client IP address or CIDR block you want to define access for needs a separate export options entry in the export. For example, if you want to set options for NFS client IP addresses 10.0.0.6, 10.0.0.08, and 10.0.0.10, you need to create three separate entries, one for each IP address.

When there is more than one export using the same file system and same mount target, the export options that are applied to an instance are the options with a source that most closely matches the instance IP address. The smallest (most specific) match takes precedence across all the exports. Therefore, you can determine which export options are applied to an instance by looking at source value of all the exports.

For example, consider the following two export options entries specifying access for an export:

Entry 1: Source: 10.0.0.8/32, Access: Read/Write

Entry 2: Source: 10.0.0.0/16, Access: Read-only

In this case, clients who connect to the export from IP address 10.0.0.8 have read/write access. When there are multiple export options, the most specific match is applied.

Important:

When more than one file system is exported to the same mount target, you must export to the mount target with the smallest network (largest CIDR number) first. For detailed information and instructions, refer to My Oracle Support document PCA File system as a Service Exports (Doc ID 2823994.1).

Important:

File systems can be associated with one or more exports, contained within one or more mount targets.

If the client source IP address does not match any entry on the list for a single export, then that export is not visible to the client. However, the file system could be accessed through other exports on the same or other mount targets. To completely deny client access to a file system, be sure that the client source IP address or CIDR block is not included in any export for any mount target associated with the file system.

For information about how to configure export options for various file sharing scenarios, see NFS Access Control Scenarios.

For more information about configuring export options, refer to the section titled Setting NFS Export Options in the File System Storage chapter in the Oracle Private Cloud Appliance User Guide.

NFS Export Option Defaults

When you create a file system and export, the NFS export options for that file system are set to the following defaults, which allow full access for all NFS client source connections. These defaults must be changed if you want to restrict access:

Note – When using the CLI to set the export options, if you set the options with an empty array (no options specified), the export is not accessible to any clients.

Export Option in the Web UI	Export Option in the CLI	Default Value	Description
Source:	`source`	0.0.0.0/0	The IP address or CIDR block of a connecting NFS client.
Ports:	`require-privileged-source-port`	Any	Always set to: Web UI: Any CLI: `false`
Access:	`access`	Read/Write	Specifies the source NFS client access. Can be set to one of these values: `READ_WRITE` `READ_ONLY`
Squash:	`identity-squash`	None	Determines whether the clients accessing the file system as root have their User ID (UID) and Group ID (GID) remapped to the squash UID/GID. These are the possible values: Root – Only the root user is remapped. None – No users are remapped.
Squash UID/GID:	`anonymous-uid`and `anonymous-gid`	65534	This setting is used along with the Squash option. When remapping a root user, you can use this setting to change the default anonymousUid and anonymousGid to any user ID of your choice.

NFS Access Control Scenarios

Learn different ways to control NFS access by reviewing these scenarios:

Scenario A: Provides a managed environment for two clients. The clients share a mount target, but each has their own file system, and cannot access each other's data.
Scenario B: Provides data to clients for consumption, but doesn't allow them to update the data.
Scenario C: Increases security by limiting the root user's privileges when connecting to a file system.

Scenario A: Control Host Based Access

Provide a managed hosted environment for two clients. The clients share a mount target, but each has their own file system, and cannot access each other's data. For example:

Client A is assigned to CIDR block 10.0.0.0/24, and requires read/write access to file system A, but not file system B.
Client B is assigned to CIDR block 10.1.1.0/24, and requires read/write access to file system B, but not file system A.
Client C is assigned to CIDR block 10.2.2.0/24, and has no access of any kind to file system A or file system B.
Both file systems A and B are associated to a single mount target, MT1. Each file system has an export contained in the export set of MT1.

Because Client A and Client B access the mount target from different CIDR blocks, you can set the client options for both file system exports to allow access to only a single CIDR block. Client C is denied access by not including its IP address or CIDR block in the NFS export options for any export of either file system.

Web UI Example

Set the export options for file system A to allow read/write access only to Client A, who is assigned to CIDR block 10.0.0.0/24. Client B and Client C are not included in this CIDR block, and cannot access the file system.

Note:

To learn how to access the NFS export options in the Compute Web UI refer the section titled Setting NFS Export Options in the File System Storage chapter of the Oracle Private Cloud Appliance User Guide.

Source	Ports	Access	Squash	Squash UID/GID
10.0.0.0/24	Any	Read/Write	None	(not used)

Set the export options for file system B to allow read/write access only to Client B, who is assigned to CIDR block 10.1.1.0/24. Client A and Client C are not included in this CIDR block, and cannot access the file system.

Source	Ports	Access	Squash	Squash UID/GID
10.1.1.0/24	Any	Read/Write	None	(not used)

CLI Example

Note:

To learn how to access the NFS export options in the OCI CLI, refer the section titled Setting NFS Export Options in the File System Storage chapter of the Oracle Private Cloud Appliance User Guide.

Set the export options for file system A to allow Read_Write access only to Client A, who is assigned to CIDR block 10.0.0.0/24. Client B and Client C are not included in this CIDR block, and cannot access the file system.

oci fs export update --export-id File_system_A_export_ID --export-options \
'[{"source":"10.0.0.0/24","require-privileged-source-port":"false","access":"READ_WRITE","identity-squash":"NONE","anonymous-uid":"65534","anonymous-gid":"65534"}]'

Set the export options for file system B to allow Read_Write access only to Client B, who is assigned to CIDR block 10.1.1.0/24. Client A and Client C are not included in this CIDR block, and cannot access the file system.

oci fs export update --export-id File_system_B_export_ID --export-options \
'[{"source":"10.1.1.0/24 ","require-privileged-source-port":"false","access":"READ_WRITE","identity-squash":"NONE","anonymous-uid":"65534","anonymous-gid":"65534"}]'

Scenario B: Limit the Ability to Write Data

Provide data to customers for consumption, but don't allow them to update the data.

For example, you'd like to publish a set of resources in file system A for an application to consume, but not change. The application connects from IP address 10.0.0.8.

Web UI Example

Set the source IP address 10.0.0.8 to read-only in the export for file system A.

Note:

Source	Ports	Access	Squash	Squash UID/GID
10.0.0.8	Any	Read-only	None	(not used)

CLI Example

Note:

To learn how to access the NFS export options in the OCI CLI, refer the section titled Setting NFS Export Options in the File System Storage chapter of the Oracle Private Cloud Appliance User Guide.

Set the source IP address 10.0.0.8 to READ_ONLY in the export for file system A.

oci fs export update --export-id File_System_A_export_OCID --export-options \
'[{"source":"10.0.0.8","require-privileged-source-port":"false","access":"READ_ONLY","identitysquash":"NONE","anonymousuid":"65534","anonymousgid":"65534"}]'

Scenario C: Improve File System Security

To increase security, you'd like to limit the root user's privileges when connecting to File System A. Use Identity Squash to remap root users to UID/GID 65534.

In UNIX-like systems, this UID/GID combination is reserved for 'nobody', a user with no system privileges.

Web UI Example

Set the source IP address 10.0.0.8 to read-only in the export for file system A.

Note:

Source	Ports	Access	Squash	Squash UID/GID
0.0.0.0/0	Any	Read/Write	Root	65534

CLI Example

Note:

To learn how to access the NFS export options in the OCI CLI, refer the section titled Setting NFS Export Options in the File System Storage chapter of the Oracle Private Cloud Appliance User Guide.

oci fs export update --export-id File_System_A_export_OCID --export-options   \
'[{"source":"0.0.0.0/0","require-privileged-source-port":"false","access":"READ_WRITE","identitysquash":"ROOT","anonymousuid":"65534","anonymousgid":"65534"}]'

File System Snapshots

The snapshot is accessible at .zfs/snapshot/ name.

File System Clones

A clone is a new file system that is created from a snapshot of an existing file system. Snapshots preserve the state of the data of a file system at a particular point in time. If you take snapshots of a file system at regular intervals, you can create clones of the file system as it existed at multiple points in its lifetime.

Cloned file systems are managed in the same way that any other file system is managed. See File System Storage in the Oracle Private Cloud Appliance User Guide.

A snapshot provides the initial blueprint for a clone. You can clone a parent file system, or you can clone a clone, as long as there's at least one snapshot available. At the point of creation, the data included in the clone is identical to the data in the snapshot. After creation, data changes in the clone aren't included in the original file system. Conversely, any data changes to the original file system aren’t included in the clone. All file systems operate independently of each other, regardless of whether they are parent file systems, clones, or clones of clones.

Clones are space and time efficient because creating a clone doesn't replicate or move any data from the parent file system to the clone. Instead, the clone references the parent file system for any data they share. A file system that is a clone of a clone also references the original parent file system for any shared data.

Parent File System

A parent file system is a file system that contains data referenced by one or many clones. When you create a clone, you must specify which file system snapshot is used as the blueprint for the clone directory hierarchy and file data. The file system that contains this snapshot is the parent of the clone. The clone continues to reference the parent file system for any data they share in common.

Source Snapshot

The snapshot used as a blueprint to create a clone. A snapshot is a point-in-time reference of a file system. You can take as many snapshots of a file system as you like, as often as you like. A parent file system can have snapshots available for many points along its lifetime. You can create a clone of your file system as it exists today, or as it existed in the past, as long as snapshots were taken of the file system at those times.

File System Clone

A clone is a new file system that is created based on a snapshot of existing file system. A clone automatically inherits the directory hierarchy and file data of the file system.

File system properties such as compartment, tags, display name, keys, and mount target export information are not copied over from the parent. These properties must be specified manually. You can access the clone by creating an export for it and mounting it to an instance in the same manner as any other file system.

Clone Tree

A clone tree is a group of clones that all descend from the same root file system. There is a transitive relationship between the root and the descendant clones. To delete the root of a clone tree, all its descendants must first be deleted.

In this diagram, B, C, D, E, F, G are all clones. A→ B→ C→D and A→ B→ E→ F→ G are all part of a clone tree. File system A is the root of this clone tree, and it is the parent of file system B.

A diagram showing file systems A through G.

Deleting File System Resources

File Systems: You can delete a file system if it is not a parent file system. If it is a parent file system, all descendant clones must first be deleted.
Snapshots: A parent snapshot can't be deleted. A snapshot that is not a parent can be deleted.
Clones: A parent clone can't be deleted. A clone that is not a parent can be deleted.