mmuserauth command

Manages the authentication configuration of file and object access protocols. The configuration allows protocol access methods to authenticate users who need to access data that is stored on the system over these protocols.

Synopsis

mmuserauth service create  --data-access-method{file|object}
              --type {ldap|local|ad|nis|userdefined}
              --servers[IP address/hostname]
              {[--pwd-file PasswordFile]--user-name | --enable-anonymous-bind} 
              [--base-dn]
              [--enable-server-tls][--enable-ks-ssl]
              [--enable-kerberos][--enable-nfs-kerberos]
              [--user-dn][--group-dn][--netgroup-dn]
              [--netbios-name]  [--domain]
              [--idmap-role{master|subordinate}][--idmap-range][--idmap-range-size]
              [--user-objectclass][--group-objectclass][--user-name-attrib]
              [--user-id-attrib][--user-mail-attrib][--user-filter]
              [ --ks-dns-name][--ks-ext-endpoint]
              [--kerberos-server][--kerberos-realm]
              [--unixmap-domains][ldapmap-domains]

mmuserauth service list [-Y] [ --data-access-method {file|object|all}]

mmuserauth service check [ --data-access-method {file|object|all}] [-r|--rectify]
            [-N|--nodes {node-list|cesNodes}][--server-reachability]

mmuserauth service remove  --data-access-method {file|object|all}[--idmapdelete]

Availability

Available on all IBM Spectrum Scale™ editions.

Description

Use the mmuserauth commands to create and manage IBM Spectrum Scale protocol authentication and ID mappings.

Parameters

service

Manages the authentication configuration of file and object access protocols with one of the following actions:

create: Configures authentication for file and object access protocols. The authentication method for file and object access protocols cannot be configured together. The mmuserauth service create command needs to be submitted separately for configuring authentication for the file and object access protocols each.
list: Displays the details of the authentication method that is configured for both file and object access protocols.
check: Verifies the authentication method configuration details for file and object access protocols. Validates the connectivity to the configured authentication servers. It also supports corrections to the configuration details on the erroneously configured protocol nodes.
remove: Removes the authentication method configuration of file and object access protocols and ID maps if any.
If you plan to remove both, authentication method configuration and ID maps, remove authentication method configuration followed by the removal of ID maps. That is, at first you need to submit the mmuserauth service remove command without the --idmapdelete option to remove the authentication method configuration and then submit the same command with the --idmapdelete option to remove ID maps.

CAUTION:
Deleting the authentication method configuration with the ID maps can lead to irrecoverable loss of access to data. Use this option with proper planning.

--data-access-method {file|object}

Specifies the access protocols for which the authentication method needs to be configured. The IBM Spectrum Scale system supports file access protocols such as SMB and NFS along with Object access protocols to access data that is stored on the system.

The file data access method is meant for authorizing the users who access data over SMB and NFS protocols.

--type {ldap|local|ad|nis|userdefined}

Specifies the authentication method to be configured for accessing data over file and object access protocols.

ldap - Defines an external LDAP server as the authentication server. This authentication type is valid for both file and object access protocols.

ad - Defines an external Microsoft Active Directory server as the authentication server. This authentication type is valid for both file and object access protocols.

local - Defines an internal database stored on IBM Spectrum Scale protocol nodes for authenticating user accessing data over object access protocol. This authentication type is valid for Object access protocol only.

nis - Defines an external NIS server as the authentication server. This authentication type is only valid for NFS file access protocol only.

userdefined - Defines user-defined ( system administrator defined ) authentication method for data access. This authentication type is valid for both file and object access protocols.

--servers [AuthServer1[:Port],AuthServer2[:Port],AuthServer3[:Port] ...]

Specifies the host name or IP address of the authentication server that is used for file and object access protocols.

This option is only valid with --type {ldap|ad|nis}.

With --type ldap, the input value format is "serverName/serverIP:[port]".

Specifying the port value is optional. Default port is 389.

For example,

--servers ldapserver.mydomain.com:1389.

For file access protocol, multiple LDAP servers can be specified by using a comma as a separator.

For the object access protocol, only one authentication server must be specified. If multiple servers are specified by using a comma, only the first server in the list is considered as the authentication server for configuration.

With --type ad, the input value format is "serverName/serverIP".

For example,

--servers ldapserver.mydomain.com.

For the file access protocol, only one authentication server must be specified. Specifying multiple servers is invalid. The AD server accepted while configuration is used to fetch details required for validation and configuration of the authentication method. Post successful configuration, each CES node will query DNS to lookout available Domain Controllers serving the AD domain it is joined to. Amongst the returned list, the node binds with the best available domain controller.

With --type nis, the input value format is "serverName/serverIP".

For example,

--servers nisserver.mydomain.com.

Multiple NIS servers can be specified by using a comma separator. At least one of the specified servers must be available and reachable while configuring the authentication method. This is important for the verification of the specified NIS domain, against which the availability of either passwd.byname or netgroup map is validated.

--base-dn ldapBase

Specifies the LDAP base DN of the authentication server. This option is only valid with --type {ldap|ad} for --data-access-method object and --type ldap for --data-access-method file.

--enable-anonymous-bind

Specifies whether to enable anonymous binding with authentication server for various validation operations.

This option is only valid with --type {ldap|ad} and --data-access-method {object}. This option is mutually exclusive with --user-name and password combination.

--user-name userName

Specifies the user name to be used to perform operations against the authentication server. This option is only valid with --type {ldap|ad} and --data-access-method {file|object}.

This option combined with password is mutually exclusive with --enable-anonymous-bind. The specified user name must have sufficient permissions to read user and group attributes from the authentication server.

In case of --type {ad|ldap} with --data-access-method object, the user name must be specified in complete DN format.

In case of --type ad with --data-access-method file, the specified username is used to join the cluster to AD domain. It results in creating a machine account for the cluster based on the --netbios-name specified in the command. After successful configuration, the cluster connects with its machine account, and not the user used during the domain join. So the specified username after domain join has no role to play in communication with the AD domain controller and can be even deleted from the AD server. The cluster can still keep using AD for authentication via the machine account created.

--pwd-file PasswordFile

Specifies the file containing passwords of administrative users for authentication configuration of file and object access protocols. The password file must be saved under /var/mmfs/ssl/keyServ/tmp on the node from which you are running the command. If this option is omitted, the command prompts for a password. The password file is a security-sensitive file and hence, must have the following characteristics:

It must be a regular file.
It must be owned by the root user.
Only the root user must have permission to read or write it.

A password file for file protocol configuration must have the following format:

%fileauth:
password=userpassword

where:

fileauth: Stanza name for file protocol
password: Specifies the password of --user-name.

Note: With --type ad for file authentication, the specified password is only required during the domain joining period. After joining the domain, the password of the machine account of the cluster is used for accessing Active Directory.

A password file for object protocol configuration must have the following format:

%objectauth:
password=userpassword
ksAdminPwd=ksAdminPwdpassword
ksSwiftPwd=ksSwiftPwdpassword

where:

objectauth: Stanza name for object protocol
password: Specifies the password of --user-name.
ksAdminPwd: Specifies the Keystone Administrator's password.
ksSwiftPwd: Specifies the Swift service user's password.

--enable-server-tls

Specifies whether to enable TLS communication with the authentication server. With --data-access-method object, this option is only valid with --type {ldap|ad}. With --data-access-method file, this option is only valid with --type {ldap}.

This option is disabled by default.

For file access protocol configuration, ensure that the CA certificate is placed in the /var/mmfs/tmp/ directory with the name ldap_cacert.pem on the node that the command is to be run.

For object access protocol configuration, ensure that the CA certificate is placed in the /var/mmfs/tmp/ directory with the name object_ldap_cacert.pem on the node that the command is to be run.

--enable-nfs-kerberos

Specifies whether to enable Kerberized logins for users gaining access by using the NFSv3 and NFSv4 file access protocols.

This option is only valid with --type {ad} and --data-access-method {file}.

This option is disabled by default.

Note: Kerberized NFSv3 and NFSv4 access is only supported for users from AD domains that are configured for fetching the UID/GID information from Active Directory (RFC2307 schema attributes). Such AD domain definition is specified by using the --unixmap-domains option.

--user-dn ldapUserDN

Specifies the LDAP group DN. Restricts search of groups within the specified sub-tree. For CIFS access, the value of this parameter is ignored and a search is performed on the baseDN.

This option is only valid with --type {ldap} and --data-access-method {file}. If this parameter is not set, the system uses the value that is set for baseDN as the default value.

--group-dn ldapGroupDN

Specifies the LDAP group suffix. Restricts search of groups within a specified sub-tree.

This option is only valid with --type {ldap} and--data-access-method {file}. If this parameter is not set, the system uses the value that is set for baseDN as the default value.

--netgroup-dn ldapGroupDN

Specifies the LDAP netgroup suffix. The system searches the netgroups based on this suffix. The value must be specified in complete DN format.

This option is only valid with --type {ldap}and --data-access-method {file}. Default value is baseDN.

--user-objectclass userObjectClass

Specifies the object class of user on the authentication server. Only users with specified object class along with other filter are treated as valid users.

If the --data-access-method is object, this option is only valid with --type {ldap|ad}.

If the --data-access-method is file, this option is only valid with --type {ldap}. With --type ldap, the default value is posixAccount and with --type ad the default value is organizationalPerson.

--group-objectclass groupObjectClass

Specifies the object class of group on the authentication server. This option is only valid with --type {ldap} and --data-access-method {file}.

--netbios-name netBiosName

Specifies the unique identifier of the resources on a network that are running NetBIOS. This option is only valid with --type {ad|ldap} and --data-access-method {file}.

The NetBIOS name is limited to 15 ASCII characters and must not contain any white space or one of the following characters: / : * ? . " ; |

If AD is selected as the authentication method, the NetBIOS name must be selected carefully. If there are name collisions across multiple IBM Spectrum Scale clusters, or between the AD Domain and the NetBIOS name, the configuration does not work properly. Consider the following points while planning for a naming strategy:

There must not be NetBIOS name collision between two IBM Spectrum Scale clusters that are configured against the same Active Directory server.
The domain join of the latter machines revokes the join of the former one.
The NetBIOS name and the domain name must not collide.
The NetBIOS name and the short name of the Domain Controllers hosting the domain must not collide.

--domain domainName

Specifies the name of the NIS domain. This option is only valid with --type {nis} and --data-access-method {file}.

The NIS domain that is specified must be served by one of the servers specified with --server. This option is mandatory when NIS-based authentication is configured for file access.

--idmap-role {master|subordinate}

Specifies the ID map role of the IBM Spectrum Scale system. ID map role of a stand-alone or singular system deployment must be selected "master". The value of the ID map role is important in AFM-based deployments.

This option is only valid with --type {ad} and --data-access-method {file}.

You can use AD with automatic ID mapping to set up two or more storage subsystems in AFM relationship. The two or more systems configured in a master-subordinate relationship provides a means to synchronize the UIDs and GIDs generated for NAS clients on one system with UIDs and GIDs on the other systems. In the AFM relationship, only one system can be configured as master and other systems must be configured as subordinates. The ID map role of master and subordinate systems are the following:

Master: System creates ID maps on its own.
Subordinate: System does not create ID maps on its own. ID maps must be exported from the master to the subordinate.

While using automatic ID mapping, in order to have same ID maps on systems sharing AFM relationship, you need to export the ID mappings from master to subordinate. The NAS file services are inactive on the subordinate system. If you need to export and import ID maps from one system to another, contact the IBM® Support Center.

--idmap-range lowerValue-higherValue

Specifies the range of values from which the IBM Spectrum Scale UIDs and GIDs are assigned by the system to the Active Directory users and groups. This option is only valid with --type {ad} and --data-access-method {file}. The default value is 10000000-299999999. The lower value of the range must be at least 1000. After configuring the IBM Spectrum Scale system with AD authentication, only the higher value can be increased (this essentially increases the number of ranges).

--idmap-range-size rangeSize

Specifies the total number of UIDs and GIDs that are assignable per domain. For example, if --idmap-range is defined as 10000000-299999999, and range size is defined as 1000000, 290 domains can be mapped, each consisting of 1000000 IDs.

Choose a value for range size that allows for the highest anticipated RID value among all of the anticipated AD users and AD groups in all of the anticipated AD domains. Choose the range size value carefully because range size cannot be changed after the first AD domain is defined on the IBM Spectrum Scale system.

This option is only valid with --type {ad} and --data-access-method {file}. Default value is 1000000.

--unixmap-domains unixDomainMap

Specifies the AD domains for which user ID and group ID should be fetched from the AD server. This option is only valid with --type {ad} and --data-access-method {file}. The unixDomainMap takes value in this format: DOMAIN1(L1-H1:{win|unix})[;DOMAIN2(L2-H2:{win|unix})[;DOMAIN3(L3-H3:{win|unix})....]]

DOMAIN

Use DOMAIN to specify an AD domain for which ID mapping services are to be configured. The name of the domain to be specified must be the NetBIOS domain name. The UIDs and GIDs of the users and groups for the specified DOMAIN are read from the UNIX attributes that are populated in the RFC2307 schema extension of AD server. Any users or groups, from this domain, with missing UID/GID attributes are denied access. Use the L-H format to specify the ID range. All the users or groups from DOMAIN that need access to exports need to have their UIDs or GIDs in the specified range.

The specified range should not intersect with:

The range specified by using the --idmap-range option of the command .
The range specified for other AD DOMAIN for which ID mapping needs to be done from Active Directory (RFC2307 schema attributes) specified in --unixmap-domains option.
The range specified for other AD DOMAIN for which ID mapping needs to be done from LDAP server specified in the --ldapmap-domains option.

The command reports a failure if you attempt to run the command with such configurations. This is intended to avoid ID collisions among users and groups from different domains.

win: Specifies the system to read the primary group set as Windows primary group of a user on the Active Directory.

unix: Specifies the system to read the primary group as set in "UNIX attributes" of a user on the Active Directory.

For example,

--unixmap-domains "MYDOMAIN1(20000-50000:unix);MYDOMAIN2(100000-200000:win)"

--ldapmap-domains ldapDomainMap

Specifies the AD domains for which user ID and group ID should be fetched from a separate standalone LDAP server. This option is only valid with --type {ad} and --data-access-method {file}. ldapDomainMap takes value of the format as follows,

DOMAIN1 (type=stand-alone:ldap_srv=ldapServer:range=Range:usr_dn=userDN:grp_dn=groupDN:[bind_dn=bindDN]
:[bind_dn_pwd=bindDNpassword])[;DOMAIN2(type=stand-alone:ldap_srv=ldapServer:range=Range:usr_dn=userDN
:grp_dn=groupDN:[bind_dn=bindDN]:[bind_dn_pwd=bindDNpassword])[;DOMAIN3(type=stand-alone:ldap_srv=ldapServer
:range=Range:usr_dn=userDN:grp_dn=groupDN:[bind_dn=bindDN]:[bind_dn_pwd=bindDNpassword])...]]

DOMAIN: Use DOMAIN to specify an AD domain for which ID mapping services are to be configured. The name of the domain to be specified must be the Pre-Win2K domain name. The UID and GID of the users and groups for the specified DOMAIN are read from the objects stored on LDAP server in RFC2307 schema attributes. Any users or groups, from this domain, with missing UID/GID attributes are denied access.

type: Defines the type of LDAP server to use.; Supported value: stand-alone.

range

Attribute takes value in the L-H format. Defines the user or group from DOMAIN that needs access to exports need to have their UIDs or GIDs in the specified range. The specified range should not intersect with,

The range specified using --idmap-range option of the command
The range specified for other AD DOMAIN for which ID mapping needs to be done from Active Directory (RFC2307 schema attributes) specified in --unixmap-domains option
The range specified for other AD DOMAIN for which ID mapping needs to be done from LDAP server specified in --ldapmap-domains option
This is intended to avoid ID collisions among users and groups from different domains.

ldap_srv: Defines the name or IP address of the LDAP server to fetch the UID or GID for of a user or group records in RFC2307 schema format. The user and group objects should be in RFC2307 schema format. Specifying only single LDAP server is supported.

user_dn: Defines the bind tree on the LDAP server where user objects shall be found.

grp_dn: Defines the bind tree on the LDAP server where the group objects shall be found.

bind_dn: Optional attribute.; Defines the user DN that should be used for authentication against the LDAP server. If not specified, anonymous bind shall be performed against the LDAP server.

bind_dn_pwd

Optional attribute.

Defines the password of the user DN specified in bind_dn to be used for authentication against the LDAP server. Must be specified when bind_dn attribute is specified for binding with the LDAP server in the DOMAIN definition.

Password cannot contain these special characters such as semicolon (;) or colon (:).

For example,

--ldapmap-domains "MYDOMAIN1(type=stand-alone:range=10000-50000
:ldap_srv=myldapserver.mydomain.com :usr_dn=ou=People,dc=mydomain,dc=com
:grp_dn=ou=Groups,dc=mydomain,dc=com :bind_dn=cn=manager,dc=mydomain,dc=com
:bind_dn_pwd=MYPASSWORD);MYDOMAIN2(type=stand-alone :range=70000-100000
:ldap_srv=myldapserver.example.com:usr_dn=ou=People,dc=example,dc=com
:grp_dn=ou=Groups,dc=example,dc=com)"

--enable-kerberos

Specifies whether to enable Kerberized logins for users who are gaining access by using file access protocols.

This option is only valid with --type {ldap} and --data-access-method {file}.

This option is disabled by default.

Note: Ensure that the legitimate keytab file is placed in the /var/mmfs/tmp directory and is named as krb5.keytab on the node that the authentication method configuration command is to be run.

--kerberos-server kerberosServer

Specifies the Kerberos server. This option is only valid with --type {ldap} and --data-access-method {file}.

--kerberos-realm kerberosRealm

Indicates the Kerberos server authentication administrative domain. The realm name is usually the all-uppercase version of the domain name. This option is case sensitive.

--user-name-attrib UserNameAttribute

Specifies the attribute to be used to search for user name on authentication server.

If the --data-access-method is object, this option is only valid with --type {ldap|ad}.

If the --data-access-method is file, this option is only valid with --type {ldap}. With --type ldap, default value is cn and with --type ad, the default value is sAMAccountName.

--user-id-attrib UserIDAttribute

Specifies the attribute to be used to search for user ID on the authentication server.

If --data-access-method is object, this option is only valid with --type {ldap|ad}.

If --data-access-method is file, this option is only valid with --type {ldap}. For --type ldap, default value is uid and for --type ad the default value is CN.

--user-mail-attrib UserMailAttribute

Specifies the attribute to be used to search for email on authentication server. If the --data-access-method is object, this option is only valid with --type {ldap|ad}. For --data-access-method file, this option is only valid with --type {ldap}. Default value is mail.

--user-filter userFilter

Specifies the additional filter to be used to search for user in the authentication server. The filter must be specified in LDAP filter format. This option is only valid with --type {ldap|ad} and --data-access-method {object}. By default, no filter is used.

--ks-dns-name keystoneDnsName

Specifies the DNS name for keystone service. The specified name must be resolved on all protocol nodes for proper functioning. This is optional with --data-access-method {object}. If the value is not specified for this parameter, the mmuserauth service create command uses the value that is used during the IBM Spectrum Scale system installation.

--ks-admin-user keystoneAdminName

Specifies the Keystone server administrative user. This user must be a valid user on authentication server if --type {ldap|ad} is specified. In case of --type local, new user is created, and admin role is assigned in Keystone. This option is mandatory with --data-access-method {object}.

For --type {ldap|ad}, do not specify user name in DN format for --ks-admin-user. The name must be the base or short name that is written against the specified user-id-attrib or user-name-attrib of user on the LDAP server.

--enable-ks-ssl

Specifies whether the SSL communication must be enabled with the Keystone service. It enables a secured way to access the Keystone service over the HTTPS protocol. The default communication option with the Keystone service is over HTTP protocol, which has security risks.

This option is only valid with --data-access-method {object}.

By default, this option is disabled.

With --type local | ad | ldap, ensure that the valid certificate files are placed in the /var/mmfs/tmp directory on the node that the command has to be run:

The SSL certificate at: /var/mmfs/tmp/ssl_cert.pem

The private key at: /var/mmfs/tmp/ssl_key.pem

The CA certificate at: /var/mmfs/tmp/ssl_cacert.pem

With --type userdefined, ensure that the valid certificate files are placed in the /var/mmfs/tmp directory on the node that the command has to be run:

The CA certificate at: /var/mmfs/tmp/ssl_cacert.pem

--ks-swift-user keystoneSwiftName

Specifies the username to be used as swift user in proxy-server.conf. If AD or LDAP-based authentication is used, this user must be available in the AD or LDAP authentication server. If local authentication method is used, new user with this name is created in the local database This option is only valid with --data-access-method {object}.

For --type {ldap|ad}, do not specify user name in DN format for --ks-swift-user. The name must be the base or short name that is written against the specified user-id-attrib or user-name-attrib of user on the LDAP server.

--ks-ext-endpoint externalendpoint

Specifies the endpoint URL of external keystone. Only API v3 and HTTP are supported. This option is only valid with --data-access-method {object} and --type {userdefined}

--idmapdelete

Specifies whether to delete the current ID maps (SID to UID/GID mappings) from the ID mapping databases for the file access method and user-role-project-domain mappings stored in local keystone database for object access method.

This option is only valid with the mmuserauth service remove command. Unless the --data-access-method parameter is specified on the command line, ID maps for file and object access protocols are erased by default. To delete the ID maps of a particular access protocol, explicitly specify the --data-access-method parameter on command line along with the valid access protocol name.

The authentication method configuration and ID maps cannot be deleted together. The authentication method configuration must be deleted before the ID maps.

Note: CAUTION: Deleting ID maps can lead to irrecoverable loss of access to data. Use this option with proper planning.

-N|--nodes{node-list|cesNodes}

Verifies the authentication configuration on each node. If the specified node is not protocol node, it is ignored. If protocol node is specified, then the system checks configuration on all protocol nodes. If you do not specify a node, the system checks the configuration of only the current node.

-Y

Displays the command output in a parseable format with a colon (:) as a field delimiter. Each column is described by a header.

Note: Fields that have a colon (:) are encoded to prevent confusion. For the set of characters that might be encoded, see the command documentation of mmclidecode. Use the mmclidecode command to decode the field.

-r|--rectify

Rectifies the authentication configurations and missing SSL and TLS certificates.

--server-reachability

Without this flag, the mmuserauth service check command only validates whether the authentication configuration files are consistent across the protocol nodes. Use this flag to ensure if the external authentication server is reachable by each protocol node.

Exit status

0: Successful completion.
nonzero: A failure has occurred.

Security

You must have root authority to run the mmuserauth command.

The node on which the command is issued must be able to run remote shell commands on any other node in the cluster without the use of a password and without producing any extraneous messages. For more information, see Requirements for administering a GPFS file system.

Examples

To configure Microsoft Active Directory (AD) based authentication with automatic ID mapping for file access, issue this command:

# mmuserauth service create --type ad --data-access-method file --netbios-name
specscale --user-name adUser --idmap-role master --servers myADserver 
--idmap-range-size 1000000 --idmap-range 10000000-299999999