Articles in this section

viewpolicy create

Sara Levy
  • Updated
Follow

This command creates a view policy. Every view has a policy. The view policy specifies part of the view's configuration. One view policy can be applied to any number of views.

Usage

viewpolicy create --name NAME 
                  --flavor NFS|SMB|MIXED_LAST_WINS|S3_NATIVE
                  --auth-source PROVIDERS|RPC_AND_PROVIDERS
                 [--access-flavor NFS4|SMB|ALL]
                 [--path-length LCD|NPL]
                 [--allowed-characters LCD|NPL]
                 [--gid-inheritance linux|bsd]
                 [--atime-frequency ATIME_FREQUENCY]
                 [--nfs-read-write [HOSTS]]
                 [--nfs-read-only [HOSTS]]
                 [--nfs-no-squash [HOSTS]]
                 [--nfs-root-squash [HOSTS]]
                 [--nfs-all-squash [HOSTS]]
                 [--enable-nfs-return-open-permissions|--disable-nfs-return-open-permissions]
                 [--enable-nfs-posix-acl|--disable-nfs-posix-acl]
                 [--enable-32bit-fileid|--disable-32bit-fileid]
                 [--enable-expose-id-in-fsid|--disable-expose-id-in-fsid]
                 [--nfs-trash-access [HOSTS]]
                 [--smb-file-mode SMB_FILE_MODE]
                 [--smb-directory-mode SMB_DIRECTORY_MODE]
                 [--vip-pool-ids POOL_IDs]
                 [--nfs-minimal-protection-level NONE|SYSTEM|KRB_AUTH_ONLY|KRB_INTEGRITY|KRB_PRIVACY]
                 [--s3-visibility USERS]
                 [--s3-visibility-groups GROUPS]
                 [--s3-read-write [HOSTS]]
                 [--s3-read-only [HOSTS]]
                 [--smb-read-write [HOSTS]]
                 [--smb-read-only [HOSTS]]
                 [--enable-apple-sid|--disable-apple-sid]
                 [--audit-protocols PROTOCOLS]
                 [--audit-operations OPERATIONS]
                 [--audit-options OPTIONS]
                 [--enable-audit-settings|--disable-audit-settings]
                 [--enable-snapshot-lookup|--disable-snapshot-lookup]
                 [--enable-listing-of-snapshot-dir|--disable-listing-of-snapshot-dir]
                 [--tenant-id ID]|[--serve-all-tenants]

Required Parameters

--name NAME

Sets a unique name for the view policy.

--flavor NFS|SMB|MIXED_LAST_WINS|S3_NATIVE

Sets a security flavor for the view policy:

  • NFS. NFS clients can set permission mode bits on files and directories when creating new files and directories or modifying existing files and directories. Attempts by SMB clients to set file and directory permissions are ignored. Files and directories created by SMB clients receive a set of initial permission bits, configurable using the --smb-file-mode and --smb-directory-mode options.

  • SMB. SMB clients can set permissions on files and directories. Attempts by NFS clients to set permission bits for files and directories are ignored. Files and directories created on NFS clients inherit permissions set on the parent directory by the SMB client.

  • MIXED_LAST_WINS. This flavor is designed to act as natively as possible to whichever protocol is used to create or modify a file or directory. It allows permissions to be set and modified from all clients. As far as possible, this flavor is designed such that whenever a user changes permissions via a given protocol, the permission change that is applied in VAST Cluster permissions is as the user intended.

    This flavor is required for NFSv4.1 with support for NFSv4 ACLs.

    See also --access-flavor for further control.

  • S3_NATIVE. Supports S3 and NFSv3. Does not support NFSv4.1 or SMB. Permissions can be changed by S3 clients using S3 ACLs. Access checks are done using the S3 access check algorithm. New buckets receive a default initial S3 bucket ACL, which gives the bucket owner FullControl. New objects receive a default initial S3 object ACL, which gives the owner FullControl.

To learn more about security modes, see: Controlling File and Directory Permissions Across Protocols.

--auth-source RPC|PROVIDERS|RPC_AND_PROVIDERS

Specifies which source is trusted for the user's group memberships, when users' access to the view is authorized. Possible values:

  • RPC. For NFSv3 only. The GIDs declared in the NFS request as the user's leading group and auxiliary groups are trusted and provider-sourced groups are not considered.

    Note

    This option is not supported for NFSv4.1.

  • PROVIDERS. Group memberships retrieved from authorization providers are considered as the user's group memberships. The GIDs declared in the request are ignored.

    Note

    This option is required for views that have SMB enabled.

    Similarly, where NFSv4.1 is enabled in the view, if Minimal Protection Level is set to Kerberos Auth-only, then this option must be used.

  • RPC_AND_PROVIDERS. Both the GIDs declared in an NFS request and group memberships retrieved from authorization providers are considered. If the GID provided by the client does not match the GID retrieved from the authorization provider, the GID from the client is set.

    Note

    If Kerberos authentication is used by NFSv4.1 clients, the groups declared in the RPC are ignored.

General Options

--vip-pool-ids POOL_IDs

Dedicates VIP pools to the view policy. Specify POOL_IDs as a comma separated list of VIP pool IDs.

For example: --vip-pool-ids 1,2,3,4

--tenant-id TENANT_ID

Associates the view policy with a specific tenant.

--serve-all-tenants

Sets the view policy to serve all tenants (default setting).

Protocol Auditing Options

Note

Any audit settings that are enabled globally for the cluster are enabled for all views. Auditing settings in a view policy can only add more protocols, operations and/or options to the audit performed on views that use this view policy.

--audit-protocols PROTOCOLS

Lists access protocols for which you are enabling or disabling protocol auditing on views that use this view policy.

Use this parameter together with --enable-audit-settings or --disable-audit-settings to enable or disable auditing of the specified protocols.

When specifying --audit-protocols , you must also specify --audit-operations and/or --audit-options.

Specify PROTOCOLS as a comma-separated list of values. Valid values:

  • NFSv3

  • NFSv4.1

  • SMB

  • S3

--audit-operations OPERATIONS

Lists categories of protocol operations for which you are enabling or disabling protocol auditing on views that use this view policy.

Use this parameter together with --audit-protocols and either --enable-audit-settings or --disable-audit-settings to enable or disable auditing of the specified protocol operations for views that use this view policy.

Specify OPERATIONS as a comma-separated list of values. Valid values:

  • create_delete_files_dirs_objects. Operations that create or delete files, directories or objects.

  • modify_data_md. Operations that modify data (this includes operations that change the file size) and metadata.

  • read_data. Operations that read data and metadata.

Tip

For a complete list of operations, see Configuring Global Auditing Settings.

--audit-options OPTIONS

Lists audit options to enable or disable on views that use this view policy.

Use this parameter together with --audit-protocols and either --enable-audit-settings or --disable-audit-settings to enable or disable the specified options for the specified protocols.

Specify OPTIONS as a comma-separated list of values. Valid values:

  • log_full_path. If enabled (default for all protocols), audit records contain the full Element Store path to the requested resource. This may affect performance. When disabled, the view path is recorded.

  • log_username. Disabled by default. If enabled, audit records contain the username (if a username can be retrieved from the auth provider).

--enable-audit-settings

Enables audit settings specified in the same command line by the --audit-protocols, --audit-operations and --audit-options parameters.

Any auditing protocols, operations options that are already enabled in the policy remain enabled.

Any audit settings (protocols, operations or options) that are already enabled in the view policy remain enabled.

--disable-audit-settings

Disables audit settings specified in the same command line by the --audit-protocols, --audit-operations and --audit-options parameters.

Any audit settings (protocols, operations or options) that are already enabled in the view policy and that are not specified in the same command line remain enabled.

NFS Security Flavor Options

--smb-file-mode SMB_FILE_MODE

--smb-directory-mode SMB_DIRECTORY_MODE

For multiprotocol views, if the security flavor is NFS, specify default Unix permission bits for files (--smb-file-mode) and directories (--smb-directory-mode). These are applied as initial permissions to files and directories created by SMB or S3 clients.

Specify SMB_FILE_MODE and SMB_DIRECTORY_MODE in three digit numeric notation, in which each digit represents a component of the permissions: user, group and others (in that order). Each digit is the sum of the following component bits:

  • If reading is permitted, the read bit adds 4 to the component.

  • If writing is permitted, the write bit adds 2 to the component.

  • If execution is permitted, the execute bit adds 1 to the component

Example

Supposing you want to set the following permissions for file mode:

user

group

others

read

permitted

permitted

permitted

write

permitted

not permitted

not permitted

execute

not permitted

not permitted

not permitted

The user's read bit (4) and a write bit (2) total 6, the group and others each have a read bit only so that is 4 each. Therefore, you set the permission bits to 644:

--smb-file-mode 644
Defaults

SMB file mode permission bits: 644

SMB directory mode permission bits: 755

S3 Options

--s3-visibility USERS

Specify users to enables those users to list buckets that are created using this policy even if they do not have permission to access those buckets.

When an S3 user sends a bucket listing request, the command returns a list of all buckets the user owns and all buckets that they have this listing permission for, even if they do not have permission to access those buckets.

Specify USERS as a comma separated list of user names.

Example: --s3-visibility jsmith,sjobs

--s3-visibility-groups GROUPS

Specify groups to enable members of those groups to list buckets that are created using this policy even if they do not have permission to access those buckets.

Specify GROUPS as a comma separated list of group names.

Example: --s3-visibility-groups interns,deptheads

S3 Host Access Options

These options set which S3 client hosts can access the view with which access types.

For each option, HOSTS can be specified as a comma separated series of any of the following:

  • A single IP.

  • A subnet indicated by CIDR notation. For example: 1.1.1.1/24.

  • A range of IPs indicated by an IP address with '*' as a wildcard in place of any of the 8-bit fields in the address. For example, 3.3.3.*, or 3.3.*.*.

The access types comprise read/write and read-only access.

If a host is specified with multiple entries in mutually exclusive access types, the conflict is resolved as follows:

  • An IP overrides a CIDR, and a CIDR overrides a wildcard expression.

  • If a conflict remains after the previous rule is applied, the read-only setting overrides the read/write setting.

By default, all hosts have read/write access.

--s3-read-write [HOSTS]

Controls which S3 client hosts have read/write access to the view.

By default, all hosts have read/write access.

To remove all hosts from read/write access, include this option without any values.

To restrict read/write access to specific hosts, specify HOSTS according to the format description above this table.

For example: --s3-read-write 98.51.100.1,98.51.100.2

--s3-read-only [HOSTS]

Specifies which S3 client hosts have read-only access to the view.

Specify HOSTS according to the format description above this table.

SMB Options

--enable-apple-sid

For use when connecting from Mac clients to SMB shares, this option enables Security IDs (SIDs) to be returned in Apple compatible representation.

--disable-apple-sid

Disables --enable-apple-sid.

SMB Host Access Options

These options set which SMB client hosts can access the view with which access types.

For each option, HOSTS can be specified as a comma separated series of any of the following:

  • A single IP.

  • A subnet indicated by CIDR notation. For example: 1.1.1.1/24.

  • A range of IPs indicated by an IP address with '*' as a wildcard in place of any of the 8-bit fields in the address. For example, 3.3.3.*, or 3.3.*.*.

The access types comprise read/write and read-only access.

If a host is specified with multiple entries in mutually exclusive access types, the conflict is resolved as follows:

  • An IP overrides a CIDR, and a CIDR overrides a wildcard expression.

  • If a conflict remains after the previous rule is applied, the read-only setting overrides the read/write setting.

By default, all hosts have read/write access.

--smb-read-write [HOSTS]

Controls which SMB client hosts have read/write access to the view.

By default, all hosts have read/write access.

To remove all hosts from read/write access, include this option without any values.

To restrict read/write access to specific hosts, specify HOSTS according to the format description above this table.

For example: --smb-read-write 98.51.100.1,98.51.100.2

--smb-read-only [HOSTS]

Specifies which SMB client hosts have read-only access to the view.

Specify HOSTS according to the format description above this table.

Advanced Multi-Protocol Options

--access-flavor NFS4|SMB|ALL

Caution

Changing this setting when already in effect on a view that is being used by clients could lead to unexpected behavior and is not advised.

If --flavor is MIXED_LAST_WINS, this parameter can be used to control which protocols can set file permissions, including Access Control Lists (ACLs) and setting user-owner and group-owner of files.

Note

NFSv3 is unaffected by this setting. NFSv3 users can set permission mode bits in Mixed Last Wins security flavor regardless of this setting.

Attempts by the blocked protocol fail silently. See Controlling File and Directory Permissions Across Protocols for details.

Possible values:

  • NFS4. Allows NFSv4.1 to set file permissions, and blocks SMB users from setting file permissions.

  • SMB. Allows SMB users to set file permissions, and blocks NFSv4.1 users from setting file permissions.

    Note

    Linux super user cannot bypass this blockage.

  • ALL (default). Allows both NFSv4.1 and SMB to set file permissions, as well as NFSv3.

--path-length LCD|NPL

Specifies the policy for limiting file path component name length.

Possible values:

  • LCD (default) (=Lowest Common Denominator). Imposes the lowest common denominator file path component length limit of all VAST Cluster-supported protocols, regardless of the specific protocol enabled on a specific view.

  • NPL (=Native Protocol Limit). Imposes no limitation beyond that of the client protocol.

    Caution

    If you select this mode in a view policy and then in the future expose a view using this policy to a previously not exposed protocol, that view might contain files that won't be accessible by the newly added protocol, due to the limitations of that protocol.

--allowed-characters LCD|NPL

Specifies the policy for which characters are allowed in file names.

Possible values:

  • LCD (default). Allows only characters allowed by all VAST Cluster-supported protocols, regardless of the specific protocol enabled on a specific view.

  • NPL. Imposes no limitation beyond that of the client protocol.

    Caution

    If you select this mode in a view policy and then in the future expose a view using this policy to a previously not exposed protocol, that view might contain files that won't be accessible by the newly added protocol, due to the limitations of that protocol.

--gid-inheritance linux|bsd

Specifies how files receive their owning group when they are created.

Possible values:

  • linux (default). Each new file inherits its owning group from the group ID of the user who creates the file.

  • bsd. Each new file inherits its owning group from the group ID of the parent directory.

NFS Host Access Options

These options set which NFS client hosts can access the view with which access types. In each access type option, HOSTS can be specified as a comma separated series of any of the following:

  • A single IP.

  • A netgroup key, which starts with '@'. This is supported for NIS netgroups if NIS is configured. For information about how to use netgroups, see Using NIS Netgroups to Authorize Host Access to NFS Exports.

    Note

    Netgroups are supported for NFSv3 only and not supported for multiprotocol views.

  • A subnet indicated by CIDR notation. For example: 1.1.1.1/24.

  • A range of IPs indicated by an IP address with '*' as a wildcard in place of any of the 8-bit fields in the address. For example, 3.3.3.*, or 3.3.*.*.

The access types comprise these categories:

  • Controlling read and write operations:

    • Read / Write. Read/write access.

    • Read Only. Read-only access.

  • Controlling squash policy:

    • No Squash. All operations are supported. Use this option if you trust the root user not to perform operations that will corrupt data.

      Note

      This option is not relevant for NFSv4.1 users if Kerberos is used, since AD does not include the 'root' user principal by default and since the handling of credentials for the user with UID 0 depends on configuration of the rpc.gssd service.

    • Root Squash. The root user is mapped to nobody for all file and folder management operations on the export. This enables you to prevent the strongest super user from corrupting all user data on the VAST Cluster.

      Note

      This option is not relevant for NFSv4.1 users if Kerberos is used, since AD does not include the 'root' user principal by default and since the handling of credentials for the user with UID 0 depends on configuration of the rpc.gssd service.

    • All Squash. All client users are mapped to nobody for all file and folder management operations on the export.

  • Controlling access to the trash folder:

    • Trash Access. This option does not appear here by default. It appears only if Enable trash folder access is enabled on the Settings page. Granting this permission gives hosts the ability to delete files by moving them into a trash folder, from which they are automatically deleted. Requires also No Squash. For more information, see Trash Folder (for Rapid Parallel File Deletion).

      Note

      This access type is applicable for NFSv3 clients only. The Trash folder feature is not supported for NFSv4.1 clients.

You can add hosts to any and all of the types, but within each category no more than one type will be applied to any given host. If a host is specified with multiple entries in mutually exclusive types, the conflict is resolved as follows:

  • An IP overrides a netgroup, a netgroup overrides a CIDR, and a CIDR overrides a wildcard expression.

  • If a conflict remains after the previous rule is applied, then:

    • Read Only overrides Read / Write.

    • All Squash overrides Root Squash.

    • Root Squash overrides No Squash.

By default, all hosts have read/write and root squash access.

--nfs-read-write [HOSTS]

Controls which NFS client hosts have read/write access to the view.

By default, all hosts have read/write access.

To remove all hosts from read/write access, include this option without any values.

To restrict read/write access to specific hosts, specify HOSTS according to the format description above this table.

For example: --nfs-read-write 98.51.100.1,98.51.100.2

--nfs-read-only [HOSTS]

Specifies which NFS client hosts have read-only access to the view.

Specify HOSTS according to the format description above this table.

--nfs-no-squash [HOSTS]

Specifies which hosts have no squash access. With no squash, all operations are supported. Use this option if you trust the root user not to perform operations that will corrupt data.

Specify HOSTS according to the format description above this table.

--nfs-root-squash [HOSTS]

Controls which hosts have root squash access. With root squash, the root user is mapped to nobody for all file and folder management operations on the export. This enables you to prevent the strongest super user from corrupting all user data on the VAST Cluster.

By default, all hosts have root squash access.

To remove all hosts from root squash access, include this option without values.

To restrict root squash to specific hosts, specify HOSTS according to the format description above this table.

--nfs-all-squash [HOSTS]

Specifies which hosts have all squash access. With all squash, all client users are mapped to nobody for all file and folder management operations on the export.

Specify HOSTS according to the format description above this table.

--nfs-trash-access [HOSTS]

Specifies which hosts have access to the trash folder, if the trash folder is enabled.

Specify HOSTS according to the format description above this table.

Note

This access type is applicable for NFSv3 clients only. The Trash folder feature is not supported for NFSv4.1 clients.

Advanced NFS Options

--atime-frequency ATIME_FREQUENCY

atime is a metadata attribute of NFS files that represents the last time the file was updated. atime is updated on read operations if the difference between the current time and the file's atime value is greater than the configured atime frequency. Consider that a very low value might have a performance impact if high numbers of files are being read.

Specify ATIME_FREQUENCY as an integer followed by a unit of time (s = seconds, m= minutes, h=hours, d=days).

Example: 1h

Default: 0, which means no atime updates.

--nfs-return-open-permissions

Sets the NFS server to unilaterally return open (777) permission for all files and directories when responding to client side access checks.

This setting works around a permissions issue that occurs with Windows clients. Windows clients perform NFSv3 access checks before executing read/write requests. This client side check uses the UID and the primary GID of the user without taking into account secondary GIDs. If the check fails, requests are not executed. This means that some permissions may not be honored as they should be, such as those based on secondary groups.

When return open permissions is enabled, VAST Cluster returns open permissions for client side access checks, so that the Windows client allows access rights and executes read/write requests. VAST Cluster does a proper permission check when the request is executed.

Caution

Use this feature with caution if Windows client systems are shared by more than one user, since the following security breach could occur: While a user is accessing a file with correct permissions and the file is cached in memory on the Windows system, if another user tries to access the same file, access is incorrectly allowed. No proper access check is done for the second user.

--disable-nfs-return-open-permissions

Disables the NFS return open permissions setting. See --nfs-return-open-permissions.

--enable-nfs-posix-acl

Enables full support of extended POSIX Access Control Lists (ACL). By default, VAST Cluster supports the traditional POSIX file system object permission mode bits, (minimal ACL mode) in which each file has three ACL entries defining the permissions for the owner, owning group, and others, respectively. To learn more about POSIX ACL, see https://linux.die.net/man/5/acl.

Note

The Posix ACL setting is relevant for NFSv3 only.

Note

The Posix ACL setting is supported only with the NFS security flavor.

Note

Thesetfacl Linux command is blocked if this option is not enabled.

Note

  • NFSv4.1 does not support POSIX ACLs.

  • If clients have created files and directories with POSIX ACLs using NFSv3 and then they start to access those files and directories via NFSv4.1, the POSIX ACLs will have no effect.

  • If this setting is enabled, POSIX ACLs may be used via NFSv3 only. They cannot be used via NFSv4.1.

  • Support for NFSv4.1 ACLs requires Mixed Last Wins security flavor and is not supported concurrently with POSIX ACLs for NFSv3.

--disable-nfs-posix-acl

Disables support for extended POSIX ACLs, restoring default minimal ACL mode.

--enable-32bit-fileid

Sets the VAST Cluster's NFS server to use 32-bit file IDs. This setting supports legacy 32-bit applications running over NFSv3.

--disable-32bit-fileid

Disables 32-bit file IDs (default).

--nfs-minimal-protection-level NONE|SYSTEM|KRB_AUTH_ONLY|KRB_INTEGRITY|KRB_PRIVACY

Set the Minimal Protection Level to accept from NFSv4.1 client RPCs:

  • KRB_PRIVACY. Allows client mounts only if they use Kerberos 5 authentication with privacy checking (krb5p), the highest level Kerberos security mode.

  • KRB_INTEGRITY. Allows client mounts only if they use either Kerberos 5 authentication with privacy checking (krb5p) or Kerberos 5 authentication with integrity (krb5i).

  • KRB_AUTH_ONLY. Allows client mounts with Kerberos authentication only and allows any of the three Kerberos security modes (krb5, krb5i, or krb5p)..

  • SYSTEM. Allows client mounts using either the AUTH_SYS RPC security flavor (the traditional default NFS authentication scheme) or with any of the three Kerberos security modes (krb5, krb5i, or krb5p).

  • NONE. Allows client mounts with the AUTH_NONE (anonymous access), or AUTH_SYS RPC security flavors, or with any of the three Kerberos security modes (krb5, krb5i, or krb5p).

Snapshot Options

--enable-snapshot-lookup

Enables accessible .snapshot directories under all directories in the view. In subdirectories of protected paths, these .snapshot directories will provide links to any existing snapshots of parent directories even if there is no protected path on the subdirectory itself. This provides easier access from each directory to snapshots of parent directories.

This setting is enabled by default.

--disable-snapshot-lookup

Disables --enable-snapshot-lookup (enabled by default). Access to a .snapshot directory under each directory is then only enabled if the directory has a protected path on it.

--enable-listing-of-snapshot-dir

If --enable-snapshot-lookup is also enabled, this setting enables listing of a snapshot directory in every directory in the view, even if there is no protected path on the specific directory. As with all snapshot directories, these are hidden directories that will appear in directory listings only for SMB clients.

--disable-listing-of-snapshot-dir

Disables --enable-listing-of-snapshot-dir if enabled. (Disabled by default).

Multiprotocol Example

In this example, we create a policy called multipro1 to attach to multiprotocol views.

In this policy, we choose to set security flavor to NFS. That enables NFS clients to set permissions on files and directories, while SMB clients will not be able to set permissions.

We will set a non-default set of permission mode bits for files and directories to inherit whenever created by SMB clients.

vcli: admin> viewpolicy create --name multipro1 --flavor nfs  --auth-source PROVIDERS --nfs-read-write 10.0.0.*  --nfs-read-only 10.0.0.1 --nfs-all-squash 10.0.0.3  --nfs-trash-access 10.0.0.1,10.0.0.4 --smb-file-mode 664 --smb-directory-mode 775

Client 10.0.0.1 has read-only access, will be root squashed and can use the trash folder.

Client 10.0.0.2 has read/write access, will be root squashed and can not use the trash folder.

Client 10.0.0.3 has read/write access, will be all squashed and cannot use the trash folder.

Client 10.0.0.4 has read/write access, will not be squashed and can use the trash folder.

Client 10.0.0.5 has read/write access, will not be squashed and cannot use the trash folder.

SMB Example

This example simply names a policy for SMB usage and enables auth provider, as required for SMB. No other view policy parameters are relevant for a policy used for views that are only exposed as SMB shares.

vcli: admin> viewpolicy create --name smbpolicy --auth-source PROVIDERS

NFS Example

In this example, a view policy intended for NFS-only views is named nfspolicy1 and gives read/write and trash folder access to one specific host while enabling read-only access for all hosts. The host given trash folder access is also not squashed, which is a necessary configuration for trash folder access to work. Remaining hosts are root squashed by default.

vcli: admin> viewpolicy create --name nfspolicy1  --auth-source RPC_AND_PROVIDERS --read-write 192.0.2.0 --nfs-read-only * --nfs-no-squash 192.0.2.0 --nfs-trash-access 192.0.2.0

Related articles

Comments

0 comments

Article is closed for comments.