Client-Side Caching for Offline Files

The SMB server provides a per-share configuration property to support client-side caching for offline files. Although the SMB server enables you to configure this feature, only the client manages client-side caching and access to offline files. You can use the zfs command to configure this feature by setting the csc property for a share.

The following are valid values for the csc property:

• manual – Permits clients to cache files from the specified share for offline use as requested by users. However, automatic file-by-file reintegration is not permitted. manual is the default value.

• auto – Permits clients to automatically cache files from the specified share for offline use, and permits file-by-file reintegration.

• vdo – Permits clients to automatically cache files from the specified share for offline use, permits file-by-file reintegration, and permits clients to work from their local cache even while offline.

• disabled – Disables client-side caching for the specified share.

Example 1-1 Configuring Client-Side Caching

The following example shows how to configure client-side caching on shares.

First, create and share a file system. When you are using SMB, it is best practice to create a mixed-mode ZFS file system, which is the default. If you have both NFS and SMB clients using a mixture of different character sets on the same file system, you might also want to set the utf8only property and consider specifying the charset=access-list NFS share property.

The share.smb property can only be set to on or off. Specifying share.smb=on during dataset creation shares the dataset with the default share properties.

# zfs create -o utf8only=on -o share.smb=on tank/zvol
# share
IPC$                            smb     -       Remote IPC
c$              /var/smb/cvol   smb     -       Default Share
tank_zvol       /tank/zvol      smb     -
# zfs get share tank/zvol%

NAME        PROPERTY         VALUE       SOURCE
tank/zvol%  name             tank/zvol%  -
tank/zvol%  share.protocols  smb         local
tank/zvol%  share.state      shared      -
tank/zvol%  share.point      /tank/zvol  -

If you specify share.smb=on during dataset creation, the share is automatically created as a default share. The name of the share is based on the share path, where slashes (/) are replaced by underscores (_).

The automatic (auto) share is represented as tank/zvol%, which is the ZFS property name for the auto share. The default share name is constructed from the file system name. Invalid characters are converted to underscores. The share.name property stores the default share name, which is the name by which the share is published. The following example uses a default share name of tank_zvol.

To list automatic shares, use the zfs list -o share command:

# zfs create -o utf8only=on -o share.smb=on tank/zvol
# zfs get share tank/zvol%
# zfs list -o share
NAME        SHARENAME  PROTOCOLS  STATE        SHAREPOINT
tank/zvol%  tank_zvol  smb        shared       /tank/zvol
zfs get share.name tank/zvol%
NAME        PROPERTY    VALUE      SOURCE
tank/zvol%  share.name  tank_zvol  -

To create a share with non-default values, use the zfs command, as shown in the following example:

First, create the dataset.

# zfs create -o utf8only=on tank/zvol

Next, create and enable an SMB share with the name of ashare.

# zfs share -o share.smb=on tank/zvol%ashare
# zfs get share tank/zvol%ashare
NAME                    PROPERTY        VALUE                   SOURCE
tank/zvol%ashare        name            tank/zvol%ashare        -
tank/zvol%ashare        share.protocols smb                     local
tank/zvol%ashare        share.state     -                       -
tank/zvol%ashare        share.point     /tank/zvol              -

Then, view the active shares on the system.

# cat /etc/dfs/sharetab
/tank/zvol ashare smb -

The following command creates a new share, bshare, with the csc property set to auto:

# zfs share -o share.smb=on -o share.smb.csc=auto tank/zvol%bshare
# zfs get share,share.smb.all tank/zvol%bshare
NAME                    PROPERTY                VALUE                   SOURCE
tank/zvol%bshare        name                    tank/zvol%bshare        -
tank/zvol%bshare        share.protocols         smb                     -
tank/zvol%bshare        share.state             -                       -
tank/zvol%bshare        share.point             /tank/zvol              -
tank/zvol%bshare        share.smb.abe           off                     default
tank/zvol%bshare        share.smb.ad-container                          default
tank/zvol%bshare        share.smb.catia         off                     default
tank/zvol%bshare        share.smb.csc           auto                    local
tank/zvol%bshare        share.smb.dfsroot       off                     default
tank/zvol%bshare        share.smb.guestok       off                     default
tank/zvol%bshare        share.smb.none                                  default
tank/zvol%bshare        share.smb.ro                                    default
tank/zvol%bshare        share.smb.rw                                    default

Using the zfs command enables you to add properties to a share without specifying all the other previously specified properties and their values.

In the following example, the first command creates a share with the name of cshare. The second command adds the csc property.

# zfs share -o share.smb=on tank/zvol3%cshare
# zfs set -o share.smb.csc=auto tank/zvol3%cshare

You can also set the csc property on autohome shares in the smbautohome map. As with the ZFS share property, multiple property-value pairs can be specified in a comma-separated list. The following smbautohome map disables client-side caching by default, but sets csc=auto for /export/home/john:

*      /export/home/&   share.smb.csc=disabled,description=&
john   /export/home/&   share.smb.csc=auto,dn=oracle,dn=com,ou=users