mmobj command

Availability

Available with IBM Spectrum Scale™ Standard Edition or higher.

Description

Use the mmobj command to modify and change the Object protocol service configuration, and to administer storage policies for object storage, unified file and object access, and multi-region object deployment.

If there is an existing object authentication configured, use the mmuserauth service remove --data-access-method object command to remove the object authentication. Then, use the mmces service disable OBJ command to perform the necessary cleanup before running the mmobj swift base command again.

Object authentication can be either local or remote. If the Object authentication is local, the Keystone identity service and the Keystone database will be running in and handled by the CES cluster. If the Object authentication is remote, the Keystone server must be fully configured and running before Object services are installed.

In the unified file and object access environment, the ibmobjectizer service can be used for making files created from the file interfaces, such as POSIX, NFS, and CIFS accessible through object interfaces, such as curl and SWIFT. The ibmobjectizer service runs periodically and makes files available for the object interface. The file-access option of the mmobj command can be used to enable and disable the file-access capability and the ibmobjectizer service. The ibmobjectizer service runs on the CES IP address with the object_singleton_node attribute.

The file-access option of the mmobj command can be used to enable object access on the files stored in an existing fileset under a container that is associated with a unified file and object access storage policy in an account.

Parameters

swift

Configures the underlying Swift services:

base

Specifies the configuration of the Object protocol service.

-g GPFSMountPoint

Specifies the mount path of the GPFS™ file system used by Swift.

GPFSMountPoint is the mount path of the GPFS file system used by the Object store.

--cluster-hostname CESHostName

Specifies the hostname which is used to return one of the CES IP addresses. The returned CES IP address is used in the endpoint for the identity and Object-store values stored in Keystone.

CESHostName is the value for cluster host name used in the identity and object-store endpoint definitions in Keystone. Ideally, it should be a hostname which will return one the CES IP addresses, such as a round-robin DNS. It could also be a fixed IP of a load balancer that distributes requests to one of the CES nodes. It is not recommended to use an ordinary CES IP since all identity and object-store requests would be routed to the single node with that address and may cause performance issues.

--local-keystone

Specifies that a new Keystone server will be installed and configured locally in the cluster.

--db-password Password

Specifies the password for the 'keystone' user in the postgres database. Defaults to the value for --admin-password.

--admin-user User

Specifies the name of the admin user in Swift. The default value is admin.

--admin-password Password

Specifies the password to be used when creating the administrator user in Keystone.

--admin-token Token

Specifies the admin token to be used for the initial Keystone setup. If it is not specified, a random string will be used.

--swift-user User

Specifies the user for the Swift services. The default value is swift.

--swift-password Password

Specifies the password for the Swift user. The default value is the password value from --admin-password.

--remote-keystone-url URL

Specifies the URL to an existing Keystone service.

--configure-remote-keystone

When a remote Keystone is used, this specifies that the remote Keystone should be configured as necessary. The required users, roles and endpoints needed by the Swift services will be added to the Keystone server. Keystone authentication information needs to be specified with the --admin-password or the --admin-token flag to enable the configuration. If this flag is not specified, the remote Keystone is not modified and the administrator will need to add the appropriate entries for the Swift configuration after the install is complete.

--admin-password Password

Specifies the password to be used when creating the administrator user in Keystone.

-o ObjFileset

Specifies the name of the fileset to be created in GPFS for the object storage.

ObjFileset is the name of the independent fileset that will be created for the Object store. By default, object_fileset is created.

-i

Specifies the maximum number of inodes for the Object fileset.

MaxNumInodes

The maximum number of inodes for the Object fileset. By default, 8000000 is set.

--ces-group

Specifies the CES group that contains the IP addresses to be used for the swift ring files. This allows you to specify a subset of the overall collection of CES IP addresses to be used by the object protocol.

--enable-s3

Sets the s3 capability (Amazon S3 API support) to true. By default, S3 API is not enabled.

--enable-file-access

Sets the file-access capability initially to true. Further configuration is still necessary using the mmobj file-access command. By default, the file-access capability is not enabled.

--enable-multi-region

Sets the multi-region capability initially to true. By default, multi-region capability is not enabled.

--join-region-file RegionFile

Specifies that this object installation will join an existing object multi-region Swift cluster. RegionFile is the region data file created by the mmobj multiregion export command from the existing multi-region cluster.

Note: The use of the --configure-remote-keystone flag is recommended so that the region-specific endpoints for this region are automatically created in Keystone.

--region-number RegionNumber

Specifies the Swift region number for this cluster. If it is not specified, the default value is to 1. In a multi-region configuration, this flag is required and must be a unique region number which is not used by another region in the multi-region environment.

config

Administers the Object configuration:

list

Lists configuration values of the underlying Swift/Keystone service stored in the CCR.

--section Section

Retrieves values for the specified section only.

The section is the heading enclosed in brackets ([]) in the associated configuration file.

--property PropertyName

Retrieves values for the specified property only.

change

Enables modifying Swift/Keystone configuration files. After you modify the configuration files, the CES monitoring framework downloads them from the CCR and distributes them to all the CES nodes in the cluster. The framework also automatically restarts the services which depend on the modified configuration files.

Note: It is recommended to not directly modify the configuration files in /etc/swift and /etc/keystone folders as they can be overwritten at any time by the files stored in the CCR.

--section Section

Specifies the section in the file that contains the parameter.

The section is the heading enclosed in brackets ([]) in the associated configuration file.

--property PropertyName

Specifies the name of the property to be set.

--value NewValue

Specifies the value of the PropertyName.

--merge-file MergeFile

Specifies a file in the openstack-config .conf format that contains multiple values to be changed in a single operation. The properties in MergeFile can represent new properties or properties to be modified. If a section or property name in MergeFile begins with a '-' character, that section or property is deleted from the file. For example, a MergeFile with the following contents would delete the ldap section, set the connections property to 512, and delete the noauth property from the database section.

[-ldap]
[database]
connections = 512
-noauth =

manage

Performs management tasks on the object configuration.

--version-sync

After an upgrade of IBM Spectrum Scale, migrates the object configuration to be consistent with the level of installed packages.

Parameter common for both mmobj config list and mmobj config change commands:

--ccrfile CCRFile

Indicates the name of the Swift, Keystone, or object configuration file stored in the CCR.

Some of the configuration files stored in the Cluster Configuration Repository (CCR) are:

• account-server.conf
• container-reconciler.conf
• container-server.conf
• object-expirer.conf
• object-server.conf
• proxy-server.conf
• swift.conf
• keystone.conf
• keystone-paste.ini
• spectrum-scale-object.conf
• object-server-sof.conf
• spectrum-scale-objectizer.conf

policy

Administers the storage policies for object storage:

list

Lists storage policies for object storage.

--policy-name PolicyName

Lists details of the specified storage policy, if it exists.

--policy-function PolicyFunction

Lists details of the storage policies with the specified function, if any exist.

--verbose

Lists the functions enabled for the storage policies.

create

Creates a storage policy for object storage. The associated configuration files are updated and the ring files are created for the storage policy. The CES monitoring framework distributes the changes to the protocol nodes and restarts the associated services.

PolicyName

Specifies the name of the storage policy.

The policy name must be unique (case insensitive), without spaces, and it must contain only letters, digits, or a dash.

-f FilesetName

Specifies the name of an existing fileset to be used for this storage policy. An existing fileset can be used provided it is not being used for an existing storage policy.

If no fileset name is specified with the command, the policy name is reused for the fileset with the prefix obj_.

--file-system FilesystemName

Specifies the name of the file system on which the fileset is created.

--i MaxNumInodes

Specifies the inode limit for the new inode space.

--enable-compression

Enables a compression policy. The Swift policy type is replication. If --enable-compression is used, --compression-schedule must be specified too and vice-versa.

Every object stored within a container that is linked to this storage policy is compressed on a scheduled basis. This occurs as a background process. For object retrieval, no decompression is needed because it occurs automatically in the background.

--compression-schedule: "MM:HH:dd:ww"

Specifies the compression schedule if --enable-compression is used. Schedule needs to be given in the MM:HH:dd:ww format :

MM = 0-59 minutes

Minute after the hour the job should be executed. The range is 0 to 59.

HH = 0-23

Hour in which the job should be executed. Hours are represented as numbers from 0 to 23.

dd = 1-31

The day of a month on which the job should be executed. Days are represented as numbers from 1 to 31.

ww = 0-7 (0=Sun, 7=Sun)

The days of the week the job should be executed. One or more values can be specified (comma separated). Days are represented as numbers from 0 to 7. 0 and 7 represent Sunday. All days of a week are represented by *. Optional. Default is 0.

• Use * for specifying every instance of a unit. For example, dd = * means that the job is scheduled to run every day.
• Comma separated lists are allowed. For example, dd = 1,3,5 means that the job is scheduled to run on every 1st, 3rd, 5th of a month.
• If ww and dd both are specified, the union is used.
• Specifying a range using - is not supported.
• Empty values are allowed for dd and ww. If empty, dd and or ww are not considered.
• Empty values for mm and hh are treaded as *.

--enable-encryption

Enables an encryption policy.

--enable-file-access

Enables a file-access policy. The file-access policies only exist in the region in which they were created. They do not support the multi-region capability. Objects stored within a container that is linked to this storage policy can be enabled for file protocol access.

--encryption-keyfile EncryptionKeyFileName

Specifies the encryption key file.

--force-rule-append

Specifies whether to append and establish the rule if other rules are already existing

Note: The enabled functions are displayed in the functions column of the mmobj policy list command output as follows:

• --enable-compression compression
• --enable-file-access file-and-object-access

change

Changes the state of the specified storage policy.

PolicyName

Specifies the name of the storage policy that needs to be changed.

--default

Sets the specified storage policy to be the default policy.

Note: You cannot set a deprecated storage policy as the default storage policy.

--deprecate State

Deprecates the specified storage policy. State can be either yes or no.

yes

Sets the state of the specified storage policy as deprecated.

no

Sets the state of the specified storage policy as not deprecated.

Note: You cannot deprecate the default storage policy.

--add-local-region

In a multi-region environment, adds the region of the current cluster to the specified storage policy. The associated fileset previously defined for the storage policy must already exist or else it is created.

After the region is added, the multi-region configuration needs to be synced with the other regions by using the mmobj multiregion command.

Note: By default, a storage policy only stores objects in the region on which it was created. If the cluster is defined as multi-region, a storage policy can also be made multi-region by adding additional regions to its definition.

--remove-region-number RegionNumber

In a multi-region environment, removes a region from the specified storage policy. The associated fileset for the storage policy is not modified.

After the region is removed, the multi-region configuration needs to be synced with the other regions by using the mmobj multiregion command.

file-access

Manages file-access capability, ibmobjectizer service and object access for files (objectizes) in a unified file and object access environment.

enable

Enables the file-access capability and the ibmobjectizer service.

If the file access capability is already enabled and the ibmobjectizer service is stopped, this option starts the ibmobjectizer service

disable

Disables the file-access capability and the ibmobjectizer service.

--objectizer

This option stops only the ibmobjectizer service, it does not disable the file-access capabilities.

objectize

Enables file(s) for object access (objectizes) in a unified file and object access environment.

--object-path ObjectPath

The fully qualified path of a file or a directory that you want to enable for access through the object interface. If a fully-qualified path to a directory is specified, the command enables all the files from that directory for access through the object interface. This is a mandatory parameter for the mmobj file-access command if the --storage-policy parameter is not specified.

--storage-policy PolicyName

The name of the storage policy for which you want to enable files for the object interface. This is a mandatory parameter for the mmobj file-access command if the --object-path parameter is not specified. If only this parameter is specified, the command enables all files for object interface from the fileset associated with the specified storage policy.

--account-name AcccountName

The account name for which you want to enable files for access through the object interface. The --storage-policy parameter is mandatory if you are using this parameter.

--container-name ContainerName

The container name for which you want to enable files for access through the object interface. You must specify the --storage-policy and the --account-name with this parameter.

--object-name ObjectName

The object name for which you want to enable files for access through the object interface. You must specify --storage-policy, --account-name, and --container-name parameters with this parameter.

-N | --node NodeName

The node on which the command is to be executed. Optional. If this parameter is not specified, the command is executed on the current node if it is a protocol node. If the current node is not a protocol node, an available protocol node is selected.

link-fileset

Enables object access to the given fileset path.

--sourcefset-path FilesetPath

The fully qualified non-object fileset path that has to be enabled for object access.

--account-name AccountName

The name of the swift account or the keystone project. The contents of the fileset will be accessible from this account when it is accessed by using the object interface.

--container-name ContainerName

The name of the container. The contents of the fileset belong to this container when it is accessed by using the object interface.

--fileaccess-policy-name PolicyName

The name of the file-access enabled storage policy.

--update-listing

Updates the container database with the existing files in the provided fileset.

If the --update-listing option is used, then the sourcefset-path must be the exact fileset junction path and the fileset must be derived from the object file system.

multiregion

Administers multi-region object deployment. For more information on multi-region object deployment and capabilities, see Overview of multi-region object deployment in IBM Spectrum Scale: Concepts, Planning, and Installation Guide.

list

Lists the information about the region.

enable

Enable the cluster for multi-region support.

Only the first cluster of the region can run the enable command. Subsequent regions join the multi-region cluster during installation with the use of the --join-region-file flag of the mmobj swift base command.

export

Exports the multi-region configuration environment so that other regions can be installed into the multi-region cluster or other regions can be synced to this region.

If successful, a region checksum is printed in the output. This checksum can be used to ensure different regions are in sync when the mmobj multiregion import command is run.

Note: When region-related information changes, such as CES IPs and storage policies, all regions must be updated with the changes.

--region-file RegionFile

Specifies a path to store the multi-region data.

This file is created.

import

Imports the specified multi-region configuration environment into this region.

If successful, a region checksum for this region is printed in the output. If the local region configuration matches the imported configuration, the checksums match. If they differ, then it means that some configuration information in the local region needs to be synced to the other regions. This can happen when a configuration change in the local region, such as adding CES IPs or storage policies, has not yet been synced with the other regions. If this is the case, the multi-region configuration for the local region needs to be exported and synced to the other regions.

--region-file RegionFile

Specifies the path to a multi-region data file created by using the mmobj multiregion export command.

remove

Completely removes a region from the multi-region environment. The removed region will no longer be accessible by other regions.

After the region is removed, the remaining regions need to have their multi-region information synced with this change by using the mmobj multiregion export and mmobj multiregion import commands.

--region-number RegionNumber

Specifies the region number that you need to remove from the multi-region configuration.

--force

Indicates that all the configuration information for the specified region needs to be permanently deleted.

s3

Enables and disables the S3 API without manually changing the configuration.

enable

Enables the S3 API.

disable

Disables the S3 API.

list

Verifies if the S3 API has been enabled or disabled.

Exit status

0

Successful completion.

nonzero

A failure has occurred.

Security

You must have root authority to run the mmobj command.

The node on which the command is issued must be able to execute 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.

See also

Location