The DBFS client command-line interface allows you to perform many pre-defined commands, such as copy files in and out of the DBFS filesystem from any host on the network.

The command-line interface has slightly better performance than the DBFS client mount interface because it does not mount the file system, thus bypassing the user space file system. However, it is not transparent to applications.

The DBFS client mount interface allows DBFS to be mounted through a file system mount point thus providing transparent access to files stored in DBFS with generic file system operations.

To run DBFS commands, specify --command to the DBFS client.

All DBFS content store paths , in command-line interface ,must be preceded by dbfs: .This is an example: dbfs:/staging_area/file1. All database path names specified must be absolute paths.

dbfs_client db_user@db_server--command command [switches] [arguments]

where:

• command is the executable command, such as ls, cp, mkdir, or rm.
• switches are specific for each command.
• arguments are file names or directory names, and are specific for each command.

Note that dbfs_client returns a nonzero value in case of failure.

You can use the ls command to list the contents of a directory.

dbfs_client db_user@db_server --command ls [switches] target

$ dbfs_client ETLUser@DBConnectString --command  ls dbfs:/staging_area/dir1

$ dbfs_client ETLUser@DBConnectString --command  ls -l -a -R dbfs:/staging_area/dir1 

You can use the cp command to copy files or directories from the source location to the destination location.

dbfs_client db_user@db_server --command cp [switches] source destination

$ dbfs_client ETLUser@DBConnectString --command cp -R  01-01-10-dump dbfs:/staging_area/

$ dbfs_client ETLUser@DBConnectString --command cp dbfs:/staging_area/hello.txt Hi.txt

You can use the command rm to delete a file or directory.

dbfs_client db_user@db_server --command rm [switches] target

$ dbfs_client ETLUser@DBConnectString --command rm  dbfs:/staging_area/srcdir/hello.txt

$ dbfs_client ETLUser@DBConnectString --command rm -R  dbfs:/staging_area/dir1

You can use dbfs_client as a mount client in Solaris 11 SRU7 and later, if you install FUSE

On Solaris, the user must have the Solaris privilege PRIV_SYS_MOUNT to perform mount and unmount operations on DBFS filesystems.

Give the user the Solaris privilege PRIV_SYS_MOUNT .

1. Edit /etc/user_attr.

2. Add or modify the user entry (assuming the user is Oracle) as follows:

   oracle::::type=normal;project=group.dba;defaultpriv=basic,priv_sys_mount;;auth s=solaris.smf.*
   

The dbfs_client mount command for Solaris and Linux uses specific syntax.

Syntax:

dbfs_client db_user@db_server [-o option_1 -o option_2 ...] mount_point

where the mandatory parameters are:

• db_user is the name of the database user who owns the DBFS content store file system.

• db_server is a valid connect string to the Oracle Database server, such as hrdb_host:1521/hrservice or an alias specified in the tnsnames.ora.

• mount_point is the path where the Database File System is mounted. Note that all file systems owned by the database user are visible at the mount point.

The options are:

• direct_io: To bypass the OS page cache and provide improved performance for large files. Programs in the file system cannot be executed with this option. Oracle recommends this option when DBFS is used as an ETL staging area.

• wallet: To run the DBFS client in the background. The Wallet must be configured to get its credentials.

• failover: To fail over the DBFS client to surviving database instances without data loss. Expect some performance cost on writes, especially for small files.

• allow_root: To allow the root user to access the filesystem. You must set the user_allow_other parameter in the /etc/fuse.conf configuration file.

• allow_other: To allow other users to access the filesystem. You must set the user_allow_other parameter in the /etc/fuse.conf configuration file.

• rw: To mount the filesystem as read-write. This is the default setting.

• ro: To mount the filesystem as read-only. Files cannot be modified.

• trace_level=n sets the trace level. Trace levels are:

  • 1 DEBUG

  • 2 INFO

  • 3 WARNING

  • 4 ERROR: The default tracing level. It outputs diagnostic information only when an error happens. It is recommended that this tracing level is always enabled.

  • 5 CRITICAL

• trace_file=STR: Specifies the tracing log file, where STR can be either a file_name or syslog.

• trace_size=trcfile_size: Specifies size of the trace file in MB. By default, dbfs_client rotates tracing output between two 10MB files. Specifying 0 for trace_size sets the maximum size of the trace file to unlimited.

You can mount a file system with a wallet after configuring various environment variables.

1. Login as admin user.
2. Mount the DBFS store. (Oracle recommends that you do not perform this step as root user.)

   % dbfs_client @/dbfsdb -o wallet,rw,user,direct_io /mnt/dbfs
   

3. [Optional] To test if the previous step was successful, as admin user, list the dbfs directory.

   $ ls /mnt/tdbfs

   Using the wallet option runs the dbfs_client in the background

   See Also:

   Using Oracle Wallet with DBFS Client

You must enter a password at the command prompt to mount a file system using dbfs_client.

In Linux, you can run fusermount to unmount file systems.

In Linux, you can configure fstab utility to use dbfs_client to mount a DBFS filesystem.

1. Login as root user.
2. Change the user and group of dbfs_client to user root and group fuse.

   # chown root.fuse $ORACLE_HOME/bin/dbfs_client
   

3. Set the setuid bit on dbfs_client and restrict execute privileges to the user and group only.

   # chmod u+rwxs,g+rx-w,o-rwx dbfs_client
   

4. Create a symbolic link to dbfs_client in /sbin as "mount.dbfs".

   $ ln -s $ORACLE_HOME/bin/dbfs_client /sbin/mount.dbfs
   

5. Create a new Linux group called "fuse".
6. Add the Linux user that is running the DBFS Client to the fuse group.
7. Add the following line to /etc/fstab:

   /sbin/mount.dbfs#db_user@db_server mount_point fuse rw,user,noauto 0 0
   

   For example:

   /sbin/mount.dbfs#/@DBConnectString /mnt/dbfs fuse rw,user,noauto 0 0
   

8. The Linux user can mount the DBFS file system using the standard Linux mount command. For example:

   $ mount /mnt/dbfs
   

   Note that FUSE does not currently support automount.

On Solaris, file systems are commonly configured using the vfstab utility.

1. Create a mount shell script mount_dbfs.sh to use to start dbfs_client. All the environment variables that are required for Oracle RDBMS must be exported. These environment variables include TNS_ADMIN, ORACLE_HOME, and LD_LIBRARY_PATH. For example:

   #!/bin/ksh
   export TNS_ADMIN=/export/home/oracle/dbfs/tnsadmin
   export ORACLE_HOME=/export/home/oracle/11.2.0/dbhome_1
   export DBFS_USER=dbfs_user
   export DBFS_PASSWD=/tmp/passwd.f
   export DBFS_DB_CONN=dbfs_db
   export O=$ORACLE_HOME
   export LD_LIBRARY_PATH=$O/lib:$O/rdbms/lib:/usr/lib:/lib:$LD_LIBRARY_PATH
   export NOHUP_LOG=/tmp/dbfs.nohup
   
   (nohup $ORACLE_HOME/bin/dbfs_client $DBFS_USER@$DBFS_DB_CONN < $DBFS_PASSWD
            2>&1 & ) &

2. Add an entry for DBFS to /etc/vfstab. Specify the mount_dbfs.sh script for the device_to_mount. Specify uvfs for the FS_type. Specify no formount_at_boot. Specify mount options as needed. For example:

   /usr/local/bin/mount_dbfs.sh - /mnt/dbfs uvfs - no rw,allow_other
   

3. User can mount the DBFS file system using the standard Solaris mount command. For example:

   $ mount /mnt/dbfs
   

4. User can unmount the DBFS file system using the standard Solaris umount command. For example:

   $ umount /mnt/dbfs
   

DBFS supports most file system operations with exceptions.

The exceptions are:

• ioctl

• range locking (file locking is supported)

• asynchronous I/O through libaio

• O_DIRECT file opens

• hard links

• other special file modes

Memory-mapped files are supported except in shared-writable mode. For performance reasons, DBFS does not update the file access time every time file data or the file data attributes are read.

You cannot run programs which user Memory mapped files from a DBFS-mounted file system if the direct_io option is specified.

Oracle does not support exporting DBFS file systems using NFS or Samba.

DBFS operates under a security model where all file systems created by a user are private to that user, by default.

Oracle recommends maintaining this model. Because operating system users and Oracle Database users are different, it is possible to allow multiple operating system users to mount a single DBFS filesystem. These mounts may potentially have different mount options and permissions. For example, OS user1 may mount a DBFS filesystem as READ ONLY, and OS user2 may mount it as READ WRITE. However, Oracle Database views both users as having the same privileges because they would be accessing the filesystem as the same database user.

Access to a database file system requires a database login as a database user with privileges on the tables that underlie the file system.The database administrator grants access to a file system to database users, and different database users may have different READ or UPDATE privileges to the file system. The database administrator has access to all files stored in the DBFS file system.

On each client computer, access to a DBFS mount point is limited to the operating system user that mounts the file system. This, however, does not limit the number of users who can access the DBFS file system, because many users may separately mount the same DBFS file system.

DBFS only performs database privilege checking. Linux performs operating system file-level permission checking when a DBFS file system is mounted. DBFS does not perform this check either when using the command interface or when using the PL/SQL interface directly.

As an operating system user who mounts the file system, you can allow root access to the file system by specifying the allow_root option.

# Allow users to specify the 'allow_root' mount option.
user_allow_other

DBFS allows multiple users to share a subset of the filesystem state.

A Single filesystem may be accessed by multiple database users. For example, the database user that owns the filesystem may be a privileged user and sharing its user credentials may pose a security risk. To mitigate this, DBFS allows multiple database users to share a subset of the filesystem state.

While DBFS registrations and mounts made through the DBFS Content API are private to each user, the underlying filesystem and the tables on which they rely may be shared across users. After this is done, the individual filesystems may be independently mounted and used by different database users, either through SQL/PLSQL, or through dbfs_client.

Learn about sharing access of DBFS to multiple database users in this section.

1. Connect as the user who creates the filesystem.

   sys@tank as sysdba> connect user1
   Connected.
   

2. Create the filesystem user1_FS, register the store, and mount it as user1_mt.

   user1@tank> exec dbms_dbfs_sfs.createFilesystem('user1_FS');
   user1@tank> exec dbms_dbfs_content.registerStore('user1_FS', 'posix', 'DBMS_DBFS_SFS');
   user1@tank> exec dbms_dbfs_content.mountStore('user1_FS', 'user1_mnt');
   user1@tank> commit;
   

3. [Optional] You may check that the previous step has completed successfully by viewing all mounts.

   user1@tank> select * from table(dbms_dbfs_content.listMounts);
   
   STORE_NAME           |   STORE_ID|PROVIDER_NAME
   ---------------------|- ---------|------------------------------------------
   PROVIDER_PKG         |PROVIDER_ID|PROVIDER_VERSION     |STORE_FEATURES
   ---------------------|-----------|---------------------|--------------------
   STORE_GUID
   ----------
   STORE_MOUNT
   ----------------------------------------------------------------------------
   CREATED
   ----------------------------------------------------------------------------
   MOUNT_PROPERTIES(PROPNAME, PROPVALUE, TYPECODE)
   ----------------------------------------------------------------------------
   user1_FS             | 1362968596|posix
   "DBMS_DBFS_SFS"      | 3350646887|0.5.0                | 12714135  141867344
   user1_mnt
   01-FEB-10 09.44.25.357858 PM
   DBMS_DBFS_CONTENT_PROPERTIES_T(
     DBMS_DBFS_CONTENT_PROPERTY_T('principal', (null), 9),
     DBMS_DBFS_CONTENT_PROPERTY_T('owner', (null), 9), 
     DBMS_DBFS_CONTENT_PROPERTY_T('acl', (null), 9), 
     DBMS_DBFS_CONTENT_PROPERTY_T('asof', (null), 187),
     DBMS_DBFS_CONTENT_PROPERTY_T('read_only', '0', 2))

4. [Optional] Connect as the user who will use the dbfs_client.

   user1@tank> connect user2
   Connected.
   

5. [Optional] Note that user2 cannot see user1's DBFS state, as he has no mounts.

   user2@tank> select * from table(dbms_dbfs_content.listMounts);
   

6. While connected as user1, export filesystem user1_FS for access to any user with DBFS_ROLE privilege.

   user1@tank> exec dbms_dbfs_sfs.exportFilesystem('user1_FS');
   user1@tank> commit;
   

7. Connect as the user who will use the dbfs_client.

   user1@tank> connect user2
   Connected.
   

8. As user2, view all available tables.

   user2@tank> select * from table(dbms_dbfs_sfs.listTables);
   
   SCHEMA_NAME                |TABLE_NAME                 |PTABLE_NAME
   ---------------------------|---------------------------|-------------------
   VERSION#
   --------------------------------CREATED
   ---------------------------------------------------------------------------
   FORMATTED
   ---------------------------------------------------------------------------
   PROPERTIES(PROPNAME, PROPVALUE, TYPECODE)
   ---------------------------------------------------------------------------
   user1                        |SFS$_FST_11                |SFS$_FSTP_11
   0.5.0
   01-FEB-10 09.43.53.497856 PM
   01-FEB-10 09.43.53.497856 PM
   (null)
   

9. As user2, register and mount the store, but do not re-create the user1_FS filesystem.

   user2@tank> exec dbms_dbfs_sfs.registerFilesystem(
      'user2_FS', 'user1', 'SFS$_FST_11');
   user2@tank> exec dbms_dbfs_content.registerStore(
      'user2_FS', 'posix', 'DBMS_DBFS_SFS');
   user2@tank> exec dbms_dbfs_content.mountStore(
      'user2_FS', 'user2_mnt');
   user2@tank> commit;
   

10. [Optional] As user2, you may check that the previous step has completed successfully by viewing all mounts.

    user2@tank> select * from table(dbms_dbfs_content.listMounts);
    
    STORE_NAME           |   STORE_ID|PROVIDER_NAME
    ---------------------|- ---------|------------------------------------------
    PROVIDER_PKG         |PROVIDER_ID|PROVIDER_VERSION     |STORE_FEATURES
    ---------------------|-----------|---------------------|--------------------
    STORE_GUID
    ----------
    STORE_MOUNT
    ----------------------------------------------------------------------------
    CREATED
    ----------------------------------------------------------------------------
    MOUNT_PROPERTIES(PROPNAME, PROPVALUE, TYPECODE)
    ----------------------------------------------------------------------------
    user2_FS             | 1362968596|posix
    "DBMS_DBFS_SFS"      | 3350646887|0.5.0                | 12714135  141867344
    user1_mnt
    01-FEB-10 09.46.16.013046 PM
    DBMS_DBFS_CONTENT_PROPERTIES_T(
      DBMS_DBFS_CONTENT_PROPERTY_T('principal', (null), 9),
      DBMS_DBFS_CONTENT_PROPERTY_T('owner', (null), 9), 
      DBMS_DBFS_CONTENT_PROPERTY_T('acl', (null), 9), 
      DBMS_DBFS_CONTENT_PROPERTY_T('asof', (null), 187),
      DBMS_DBFS_CONTENT_PROPERTY_T('read_only', '0', 2))

11. [Optional] List path names for user2 and user1. Note that another mount, user2_mnt,for store user2_FS, is available for user2. However, the underlying filesystem data is the same for user2 as for user1.

    user2@tank> select pathname from dbfs_content;
     
    PATHNAME
    -------------------------------------------------------------------------------
    /user2_mnt
    /user2_mnt/.sfs/tools
    /user2_mnt/.sfs/snapshots
    /user2_mnt/.sfs/content
    /user2_mnt/.sfs/attributes
    /user2_mnt/.sfs/RECYCLE
    /user2_mnt/.sfs
    
    user2@tank> connect user1
    Connected.
    
    user1@tank> select pathname from dbfs_content;
     
    PATHNAME
    ---------------------
    /user1_mnt
    /user1_mnt/.sfs/tools
    /user1_mnt/.sfs/snapshots
    /user1_mnt/.sfs/content
    /user1_mnt/.sfs/attributes
    /user1_mnt/.sfs/RECYCLE
    /user1_mnt/.sfs
    

12. In filesystem user1_FS, user1 creates file xxx.

    user1@tank> declare
                    data blob;
                    properties dbms_dbfs_content.properties_t;
                begin
                    properties('posix:mode') := dbms_dbfs_content.propNumber(33188);
                    dbms_dbfs_content.createFile('/user1_mnt/xxx', properties => properties, content => data);
                end;
                /

13. [Optional] Write to file xxx, created in the previous step.

    user1@tank> var buf varchar2(100);
    user1@tank> exec :buf := 'hello world';
    user1@tank> exec dbms_lob.writeappend(:data, length(:buf), utl_raw.cast_to_raw(:buf));
    user1@tank> commit;
     

14. [Optional] Show that file xxx exists, and contains the appended data.

    user1@tank> select pathname, utl_raw.cast_to_varchar2(filedata) 
      from dbfs_content where filedata is not null;
     
    PATHNAME
    -------------------------------------------------------------------------------
    UTL_RAW.CAST_TO_VARCHAR2(FILEDATA)
    -------------------------------------------------------------------------------
    /user1_mnt/xxx
    hello world
    

15. User user2 sees the same file in their own DBFS-specific path name and mount prefix.

    user1@tank> connect user2
    Connected.
     
    user2@tank> select pathname, utl_raw.cast_to_varchar2(filedata) from
      dbfs_content where filedata is not null;
     
    PATHNAME
    -------------------------------------------------------------------------------
    UTL_RAW.CAST_TO_VARCHAR2(FILEDATA)
    -------------------------------------------------------------------------------
    /user2_mnt/xxx
    hello world
    

To provide database users who have DBFS authentication with a hierarchical file system-like view of registered and mounted DBFS stores, stores are displayed under the path /dbfs.

The /dbfs folder is a virtual folder because the resources in its subtree are stored in DBFS stores, not the XDB repository. XDB issues a dbms_dbfs_content.list() command for the root path name "/" (with invoker rights) and receives a list of store access points as subfolders in the /dbfs folder. The list is comparable to store_mount parameters passed to dbms_dbfs_content.mountStore(). FTP and WebDAV users can navigate to these stores, while HTTP and HTTPS users access URLs from browsers.

Note that features implemented by the XDB repository, such as repository events, resource configurations, and ACLs, are not available for the /dbfs folder.

DBFS Content API for guidelines on DBFS store creation, registration, deregistration, mount, unmount and deletion

WebDAV is an IETF standard protocol that provides users with a file-system-like interface to a repository over the Internet.

WebDAV server folders are typically accessed through Web Folders on Microsoft Windows (2000/NT/XP/Vista/7, and so on). You can access a resource using its fully qualified name, for example, /dbfs/sfs1/dir1/file1.txt, where sfs1 is the name of a DBFS store.

You need to set up WebDAV on Windows to access the DBFS filesystem.

The user authentication required to access the DBFS virtual folder is the same as for the XDB repository.

When a WebDAV client connects to a WebDAV server for the first time, the user is typically prompted for a username and password, which the client uses for all subsequent requests. From a protocol point-of-view, every request contains authentication information, which XDB uses to authenticate the user as a valid database user. If the user does not exist, the client does not get access to the DBFS store or the XDB repository. Upon successful authentication, the database user becomes the current user in the session.

XDB supports both basic authentication and digest authentication. For security reasons, it is highly recommended that HTTPS transport be used if basic authentication is enabled.

FTP access to DBFS uses the standard FTP clients found on most Unix-based distributions. FTP is a file transfer mechanism built on client-server architecture with separate control and data connections.

FTP users are authenticated as database users. The protocol, as outlined in RFC 959, uses clear text user name and password for authentication. Therefore, FTP is not a secure protocol.

The following commands are supported for DBFS:

• USER: Authentication username

• PASS: Authentication password

• CWD: Change working directory

• CDUP: Change to Parent directory

• QUIT: Disconnect

• PORT: Specifies an address and port to which the server should connect

• PASV: Enter passive mode

• TYPE: Sets the transfer mode, such as, ASCII or Binary

• RETR: Transfer a copy of the file

• STOR: Accept the data and store the data as a file at the server site

• RNFR: Rename From

• RNTO: Rename To

• DELE: Delete file

• RMD: Remove directory

• MKD: Make a directory

• PWD: Print working directory

• LIST: Listing of a file or directory. Default is current directory.

• NLST: Returns file names in a directory

• HELP: Usage document

• SYST: Return system type

• FEAT: Gets the feature list implemented by the server

• NOOP: No operation (used for keep-alives)

• EPRT: Extended address (IPv6) and port to which the server should connect

• EPSV: Enter extended passive mode (IPv6)

Users have read-only access through HTTP/HTTPS protocols.

Users point their browsers to a DBFS store using the XDB HTTP server with a URL such as https://hostname:port/dbfs/sfs1 where sfs1 is a DBFS store name.