mmobj command
Manages configuration of Object protocol service, and administers storage policies for object storage, unified file and object access, and multi-region object deployment.
Synopsis
mmobj swift base -g GPFSMountPoint --cluster-hostname CESHostName
[-o ObjFileset] [-i MaxNumInodes]
{{{--local-keystone [--db-password Password] [--admin-token Token]}
| [--remote-keystone-url URL} [--configure-remote-keystone]}
--admin-password Password [--admin-user AdminUser]
[--swift-user SwiftUser ] [--swift-password SwiftPassword]
[--enable-file-access] [--enable-s3] [--enable-multi-region]
[--join-region-file RegionFile] [--region-number RegionNumber]
or
mmobj config list --ccrfile CCRFile [--section Section [--property PropertyName]]
or
mmobj config change --ccrfile CCRFile --section Section --property PropertyName --value Value
or
mmobj config change --ccrfile CCRFile --merge-file MergeFile
or
mmobj policy list [[--policy-name PolicyName] | [--policy-function PolicyFunction]] [--verbose]
or
mmobj policy create PolicyName [-f FilesetName] [-i MaxNumInodes]
{[--enable-compression --compression-schedule CompressionSchedule]}
[--enable-file-access]
or
mmobj policy change PolicyName --default
or
mmobj policy change PolicyName --deprecate State
or
mmobj policy change --add-local-region
or
mmobj policy change --remove-region-number RegionNumber
or
mmobj file-access {--object-path ObjectPath | --storage-policy PolicyName
[--account-name AccountName [--container-name ContainerName
[--object-name ObjectName]]]} [--node NodeName]
or
mmobj multiregion list
or
mmobj multiregion enable
or
mmobj multiregion export --region-file RegionFile
or
mmobj multiregion import --region-file RegionFile
or
mmobj multiregion remove --region-number RegionNumber --force
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.
- The node with the object_database_node attribute runs the keystone database.
- The node with the object_singleton_node attribute runs unique object services across the CES cluster.
In case of a complete reconfiguration, use the mmces service disable OBJ command to perform 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.
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.
- --enable-s3
- Sets the s3 capability (Amazon S3 emulation support) to true. By default, S3 emulation 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 =
- 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 the fileset that must be used or created for the 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_.
- --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-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.
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
- 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 for which you want to enable access through the object interface. If a fully qualified path to a directory is specified then 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.
- --node NodeName
- The node on which the command is to be executed. Optional. If this parameter is not specified, the command is executed from the current node if it is a protocol node. If the current node is not a protocol node, an available protocol node is selected.
- 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.
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 file system in IBM Spectrum Scale: Administration and Programming Reference.
Examples
- To specify configuration of Object protocol service with local
keystone and S3 enabled, issue this command:
The system displays output similar to this:mmobj swift base -g /gpfs/ObjectFS --cluster-hostname cluster-ces-ip.ibm --local-keystone --enable-s3 --admin-password Passw0rd
mmobj swift base: Creating fileset /dev/ObjectFS object_fileset mmobj swift base: Configuring Keystone server in /gpfs/ObjectFS/ces/object/keystone mmobj swift base: Configuring Swift services Configuration complete
- To list object configuration settings for proxy-server.conf,
DEFAULT section, issue this command:
The system displays output similar to this:mmobj config list --ccrfile proxy-server.conf --section DEFAULT
[DEFAULT] bind_port = 8080 workers = auto user = swift log_level = ERROR
- To change the number of worker processes that each object server
launches, update the object-server.conf file
as shown here:
mmobj config change --ccrfile object-server.conf --section DEFAULT --property workers --value 16
- To change the configuration value of paste.filter_factory which
is in the filter:s3_extension section of the keystone-paste.ini configuration
file, issue the command:
mmobj config change --ccrfile keystone-paste.ini --section filter:s3_extension --property paste.filter_factory --value keystone.contrib.s3:S3Extension.factory
- To create a new storage policy CompressionTest with
the expiration function enabled and with the expiration time specified,
issue this command:
The system displays output similar to this:mmobj policy create CompressionTest --enable-compression
[I] Getting latest configuration from ccr [I] Creating fileset /dev/gpfs0:obj_CompressionTest [I] Creating new unique index and build the object rings [I] Updating the configuration [I] Uploading the changed configuration
- To list storage policies for object storage with details of functions
available with those storage policies, issue this command:
The system displays output similar to this:mmobj policy list --verbose
Index Name Deprecated Fileset Fileset Path Functions Function Details ------------------------------------------------------------------------------------------------------------------------------------ 0 SwiftDefault object_fileset /ibm/cesSharedRoot/object_fileset 11751509160 sof-policy obj_sof-policy /ibm/cesSharedRoot/obj_sof-policy file-and-object-access regions="1" 11751509230 mysofpolicy obj_mysofpolicy /ibm/cesSharedRoot/obj_mysofpolicy file-and-object-access regions="1" 11751510260 Test19 obj_Test19 /ibm/cesSharedRoot/obj_Test19 regions="1"
- To enable object access for an account, issue this command:
mmobj file-access --storage-policy sof_policy --account-name admin
The system displays output similar to the following:
Loading objectization configuration from CCR Fetching storage policy details Creating container to database map Performing objectization Objectization complete
- To enable object access for a container, issue this command:
mmobj file-access --storage-policy sof_policy --account-name admin --container-name container1
- To enable object access on a file while specifying a storage policy,
issue this command:
mmobj file-access --storage-policy sof_policy --account-name admin --container-name container1 --object-name file1.txt
- To enable object access on a file, issue this command:
mmobj file-access --object-path /ibm/gpfs0/obj_sofpolicy1/s69931509221z1device1/AUTH_12345/container1/file1.txt
- To list the information about a region, issue this command:
mmobj multiregion list
The system displays output similar to this:
Region Endpoint Cluster Name Cluster Id ------ --------- --------------- ------------------- 1 RegionOne europe.gpfs.net 3694106483743716196 2 Region2 asia.gpfs.net 1860802811592373112
- To set up the initial multi-region environment on the first region,
issue this command:
mmobj multiregion enable
The system displays output similar to this:
mmobj multiregion: Multi-region support is enabled in this cluster. Region number: 1
- To export multi-region data for use by other clusters to join
multi-region, issue this command:
mmobj multiregion export --region-file /tmp/region2.dat
The system displays output similar to this:
mmobj multiregion: The Object multi-region export file was successfully created: /tmp/region2.dat mmobj multiregion: Region checksum is: 34632-44791
- To import the specified multi-region configuration environment
created by the export command into a region, issue this command:
mmobj multiregion import --region-file /tmp/region2.dat
The system displays output similar to this:
mmobj multiregion: The region config has been updated. mmobj multiregion: Region checksum is: 34632-44791
- To remove a region designated by region number 2 from a multi-region
environment and to remove all configuration information of the specified
region, issue this command:
mmobj multiregion remove --remove-region-number 2 --force
The system displays output similar to this:
mmobj multiregion: Permanently removing region 2 (asia.gpfs.net 1860802811592373112) from multi-region configuration. mmobj multiregion: Updating ring files. mmobj multiregion: Successfully removed region 2. Object services on region 2 will need to be unconfigured and its endpoint removed from Keystone.