OCIVFS mounts one Oracle Cloud Infrastructure Object Storage bucket: every
object becomes a file and every / in a key a folder. It reaches OCI through
the Amazon S3 Compatibility API. Set up credentials as in OCI setup.
Install
Configure
namespace and region build the endpoint
https://<namespace>.compat.objectstorage.<region>.oci.customer-oci.com;
endpoint replaces it. A mount takes MountMode.READ, WRITE or EXEC.
Fields
Named profile in the shared AWS config and credentials files that supplies credentials when no access key pair is given.
Address the bucket in the URL path (
<endpoint>/<bucket>/<key>) instead of as a subdomain of the endpoint.Key prefix inside the bucket that the mount treats as its root; keys outside it are not visible. Leading slashes are dropped and a trailing
/ is added.Seconds a request may wait to connect, or between two reads of its answer, before it fails; a download that keeps flowing is never cut off.
Provider region every request is signed for. Most providers also build their endpoint URL from it unless
endpoint is set.Object Storage namespace of the tenancy. With
region it builds the endpoint https://<namespace>.compat.objectstorage.<region>.oci.customer-oci.com unless endpoint is set.Authentication
Credentials come fromaccessKeyId and secretAccessKey, a Customer Secret
Key, with sessionToken for temporary credentials. Without them, the AWS SDK
reads its own chain: environment variables, ~/.aws/credentials, then the
instance or container role.
The user’s group needs policies such as
Allow group <group> to read buckets in compartment <compartment> and
Allow group <group> to manage objects in compartment <compartment>
(read objects for a read-only mount). A request the credentials may not make
answers Permission denied.
Layout
/oci/data/file.txt is the key data/file.txt. Folders come from the / in
keys; OCI stores no folder objects.
Behavior
- Key prefix:
keyPrefix: 'users/42/'mounts only that part of the bucket, so/oci/notes.mdis the keyusers/42/notes.md. - Path style: the S3 Compatibility API takes only path-style URLs, so
forcePathStyledefaults totrue.
Browser
The browserOCIVFS from @struktoai/mirage-browser keeps credentials off the
page: a server signs a URL for each S3 call with the OCI keys, and the browser
fetches it.
- The S3 Compatibility API answers CORS for any origin by default. Its CORS
rules cannot be set through the S3
PutBucketCorscall. - A browser mount cannot declare
write: conditional, and any HTTP 403 from a signed URL, an expired one included, answersPermission denied. keyPrefixset in the browser is no security boundary: enforce the prefix in the signing server.namespace,regionandendpointonly name the mount’s storage location: requests go to the host each signed URL names.
Signing server
Signing server
An Express route that signs URLs:Sign only the operations the app needs: a viewer needs
GET, HEAD and LIST.Browser fields
Browser fields
Function
(path, operation, options) that returns a signed URL for each S3 operation; your server signs it, so the browser holds no keys.Region of the bucket. Most providers derive the endpoint from it; requests go to the host each presigned URL names.
Endpoint URL that replaces the one the provider derives. Requests go to the host each presigned URL names; the mount uses it to name its storage location.
Key prefix the mount treats as its root. The browser can change it before a URL is signed, so enforce the prefix on the signing server.
Seconds a request may wait to connect, or between two reads of its answer, before it fails; a download that keeps flowing is never cut off.
Object Storage namespace of the tenancy. With
region it builds the endpoint https://<namespace>.compat.objectstorage.<region>.oci.customer-oci.com unless endpoint is set.Integration
OCI answers these commands through its own API, so fewer objects are read. See Integration.find: one recursive listing.du: one recursive listing.ls -Randtree: one recursive listing.
VFS.md
The VFS.md an agent reads with OCI mounted at/<path>.
<mode> is the mount’s mode: read, write or exec. The commands shown are
those of a write mount.
- Rendered
- Raw
Virtual Filesystem
Supported Unix Commands for VFSUnix commands work on each path as on a local filesystem, as far as the path supports them:
Limitations of Unix Commands for VFSWhere a path differs from a local filesystem:
Run
man <cmd> or <cmd> --help for one command’s usage.