mmcallhome command

Manages the call home operations.

Synopsis

mmcallhome group add groupName server  [--node {all | childNode[,childNode...]}]

mmcallhome group list [--long] [-Y]

mmcallhome group delete GroupName


mmcallhome group auto [--server ServerName1[,ServerName2...]]
                      [--nodes {all | ChildNode1[,ChildNode2...]}]
                      [--force]
                      [--group-names  {group1[,group2...]}]
                      [--enable [ {LICENSE | ACCEPT}] |--disable]

mmcallhome capability list [-Y]

mmcallhome capability enable [{LICENSE | ACCEPT}]

mmcallhome capability disable

mmcallhome info list [-Y]

mmcallhome info change  { --customer-name  CustomerName | --customer-id CustomerId  
                        | --email Email | --country-code CountryCode } ...

mmcallhome proxy enable [--with-proxy-auth]

mmcallhome proxy disable

mmcallhome proxy list [-Y]

mmcallhome proxy change { --proxy-location  ProxyLocation | --proxy-port ProxyPort
                        | --proxy-username  ProxyUsername | --proxy-password  ProxyPassword } ...

mmcallhome schedule list [-Y]

mmcallhome schedule add --task { DAILY | WEEKLY }

mmcallhome schedule delete --task { DAILY | WEEKLY }

mmcallhome run GatherSend --task { DAILY | WEEKLY }

mmcallhome run SendFile --file file [--desc DESC | --pmr {xxxxx.yyy.zzz | TSxxxxxxxxx}]

mmcallhome status list [--task { DAILY  | WEEKLY  | SENDFILE  | SENDPMRDATA }] 
                       [--numbers num] [--verbose ] [-Y]

mmcallhome status delete {--task { DAILY  | WEEKLY  | SENDFILE  | SENDPMRDATA  } | 
                          --startTime time | --startTimeBefore time | --all }

mmcallhome test connection

Availability

Available on all IBM Spectrum Scale editions.

Description

Use the mmcallhome command to configure, enable, run, schedule, and monitor call home related tasks in the IBM Spectrum Scale cluster.

By using this command, predefined data from each node can be collected on a regular basis or on demand and uploaded to IBM®. IBM support and development teams can use this data to understand how the customers are using IBM Spectrum Scale. In case of issues, the data can be referenced for problem analysis. The data can also possibly be used to provide advice to customers regarding failure prevention.

Since an IBM Spectrum Scale cluster consists of multiple nodes, the call home feature introduces the concept of the call home group to manage them. A call home group consists of one gateway node (which is defined as a call home node) and one or more client nodes (which are defined as call home child nodes). The call home node initiates the data collection from the call home child nodes and uploads data to IBM using the HTTPS protocol. Since the call home group can be configured independently, the group concept can be used for special conditions, such as for split clusters, that require all the group members to be on the same side to avoid unnecessary data transfer over large distance. Also, a call home group can be mapped to a node group or other cluster-specific attributes. The call home node needs to have access to the external network via port 443. The maximum recommended number of nodes per group is 128. Each cluster node can be only a member of at most one group. Multiple call home groups can be defined within an IBM Spectrum Scale cluster.

For more information about the call home feature, see Monitoring the IBM Spectrum Scale system by using call home.

Parameters

group

Manages topology with one of the following actions:

add

Creates a call home group, which is a group of nodes consisting of one call home node and multiple call home child nodes. Multiple call home groups can be configured within an IBM Spectrum Scale cluster.

The call home node initiates data collection within the call home group and uploads the data package to the IBM server.

group: Specifies the name of the call home group.
Note: The group name can consist of any alphanumeric characters and these non-alphanumeric characters: '-', '_', and '.'.

Important: The group name cannot be global. Call home uses global as the default name for the group that contains the global values that are applied to all groups.

server: Specifies the name of the call home server belonging to the call home group.
Note: The server name can consist of any alphanumeric characters and these non-alphanumeric characters: '-', '_', and '.

--node childNode: Specifies the call home child nodes.
Note: The child node name can consist of any alphanumeric characters and these non-alphanumeric characters: '-', '_', and '.

--node all: Selects all Linux nodes in the IBM Spectrum Scale cluster. When this parameter is omitted, only the call home node is added to the child node. Additionally, call home node is always added to the child node group.

list

Displays the configured call home groups.

Note:

If nodes that are members of a call home group are deleted, or their long admin node names (including domain) are changed, the mmcallhome group list command displays ------ instead of the names of such nodes. In such cases, you must delete the corresponding groups, and then create new groups if needed. The deletion of the call home groups is not done automatically, since in some cases this might cause the deletion of the call home groups without re-creating them.

--long: Displays the node names as long admin node names. Without --long the node names are listed as short admin node names.

-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.

delete

Deletes the specified call home group.

GroupName: Specifies the name of the call home group that needs to be deleted.

auto

Enables automatic creation of call home groups.

--server ServerName: Specifies one or more call home servers. Each server must be able to access the IBM call home servers over the internet. If no server is specified, the system detects call home node automatically. In this scenario, the system checks if the detected node can access the internet. If a server is specified, the defined nodes are used as call home nodes without any further check.
If a proxy is needed, specify the proxy by using the mmcallhome proxy command before running the mmcallhome group auto command.

Note: If this option is specified, the corresponding nodes are assumed to be able to access the IBM call home servers over the internet and no further checks in this regard is performed. If this option is not used, the mmcallhome command tests all potential call home nodes for the connectivity to the IBM call home servers. In this case, if a proxy is configured via the mmcallhome proxy command, this proxy is used to check the connectivity, otherwise a direct connection is attempted.

--nodes

Specifies the names of the call home child nodes to distribute into groups.

all: Specifies that all cluster nodes must be distributed into call home groups.

--force: Creates new groups after deleting the existing groups.
Note: If this option is selected but no server nodes are specified using the --server option or detected automatically, the operation is aborted and the existing groups are not deleted.

--group-names: Specifies the names of the call home groups to create. The number of call home group names must be bigger or equal to the number of created call home groups or the execution of the mmcallhome group auto command is aborted with an error. If this option is not specified, the automatically created groups are named in the following way: autoGroup_1, autoGroup_2, ...

--enable

Enables the cluster for call home functionality. If no other option is defined, the enable parameter shows the license and asks for acceptance by default.

LICENSE: Shows license and terminate.
ACCEPT: Does not show license and assumes that the license is accepted.

--disable

Disable call home.

Note: All groups are disabled.

capability

Manages the overall call home activities with one of the following actions:

list

Displays the configured customer information such as the current enable or disable status, call home node, and call home child nodes.

-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.

enable

Enables the call home service.

disable

Disables the currently running call home service.

info

Manages customer data with one of the following actions:

list

Displays the configured parameter values.

-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.

change

Sets parameter values.

[--key value]

Indicates a placeholder pointing to the following table:

Table 1. Key-value
Key	Value
customer-name	Business/company name This name can consist of any alphanumeric characters and these non-alphanumeric characters: '-', '_', '.', ' ', ','
customer-id	Customer ID This can consist of any alphanumeric characters and these non-alphanumeric characters: '-', '_', '.'
email	Group or task e-mail address only. Ensure that the call home contact information is not a personal e-mail address, and is directed towards a group or task e-mail address. For example, itsupport@mycompanyname.com.
country-code 2 alphabet ISO	Country code (Example, US)

proxy

Configures proxy-related parameters with one of the following actions:

enable

Enables call home to use a proxy for its uploads. Requires the call home settings proxy-location and proxy-port to be defined.

[--with-proxy-auth]: Enables user ID and password authentication to the proxy server. Requires the call home settings proxy-username and proxy-password to be set.

disable

Disables proxy access.

list

Displays the currently configured proxy-related parameter values.

-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.

change

Modifies the proxy configuration.

[--key value]

Indicates a placeholder pointing to the table below.

Table 2. key-value
Key	Value
proxy-location	Proxy server address (IP address/fully qualified domain name)
proxy-port	Proxy server port number
proxy-username	Proxy server user name This name can consist of any alphanumeric and non-alphanumeric characters.
proxy-password	Proxy server password This can consist of any alphanumeric and non-alphanumeric characters.

schedule

Configures scheduling of call home tasks with one of the following actions:

list

Displays the registered gather-send tasks. A gather-send task is a process that runs on the call home node to collect data from the child nodes and upload the data to the configured server. The gather-end configuration file will include information about what needs to be collected from the child nodes.

-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.

add

Registers the specified task to cron.

--task daily: Specifies the configuration file for the daily task.

--task weekly: Specifies the configuration file for the weekly task.

delete

Removes a daily or weekly task from cron with one of the following options:

--task daily: Specifies the daily task that needs to be removed from cron.

--task weekly: Specifies the weekly task that needs to be removed from cron.

run

Executes one-time gather or send tasks with one of the following options:

GatherSend

Executes a one-time gather-send task, which collects the predefined data and uploads it.

--task daily: Specifies that the data, defined in daily.conf, or DefaultDaily.ess.conf on ESS, must be collected and uploaded.

--task weekly: Specifies that the data, defined in weekly.conf, or DefaultWeekly.ess.conf on ESS, MUST be collected and uploaded.

SendFile

Uploads a specified file to IBM, with the following options:

--file file: Specifies the name of the file that needs to be uploaded.
Note: The name can consist of any alphanumeric characters and these non-alphanumeric characters: '-', '_', '.'

[--desc DESC]: Specifies the description of the file that needs to be uploaded. This is added to the data package file name.
Note: This text can consist of any alphanumeric characters and these non-alphanumeric characters: '-', '_', '.', ' ', ','

[--pmr {xxxxx.yyy.zzz | TSxxxxxxxxx}]: Specifies either the dot-delimited PMR descriptor, where x, y and z could be digits, and y might additionally be a letter, or a Salesforce case descriptor, where each x is a digit.

status

Displays status of the call home tasks with one of the following options:

list

Displays the status of the currently running and the already completed call home tasks.

--task {DAILY | WEEKLY | SENDFILE | SENDPMRDATA}

Specifies the requested call home task type. The following types are available:

DAILY: Daily executed scheduled uploads.
WEEKLY: Weekly executed scheduled uploads.
SENDFILE: Files that are sent on demand, that are not PMR related or Salesforce case related.
SENDPMRDATA: Files that are sent on demand, that are either PMR related or Salesforce case related.

[--numbers num]: Specifies the maximum number of latest tasks that can be listed for each requested task type.

-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.

--verbose: Lists additional information.

When the mmcallhome status list --verbose command is executed, the following information is shown in the output:

Group: The name of the call home group where the task was executed.
Task: Type of the executed call home task: DAILY, WEEKLY, SENDFILE or SENDPMRDATA.
Start Time: A time stamp, specifying the start time of the call home task. This timestamp is also used to uniquely identify a call home task within a call home group.
Updated Time: A time stamp of the last status update for the corresponding task.
Status: You can get one of the following values as status information:
- success
- running
- failed
- minor error
- aborted
RC or Step:
- For a task that is currently running, the current execution step is displayed.
- For a successful task, RC=0 is displayed.
- For a failed task, the failure details are displayed.
Package File Name: Name of the created data package to be uploaded.
Original Filename: Name of the transferred file for the SendFile tasks.

delete

Deletes the status log entries for the specified tasks:

--task {DAILY | WEEKLY | SENDFILE | SENDPMRDATA}: Specifies the task type, for which the status log entries should be deleted.

--startTime starttime: Specifies the start time of the log to delete.

--startTimeBefore starttime: All logs older than the time specified by this option are deleted.

--all: All logs are deleted.

test

Executes detailed system checks:

connection: Checks the connectivity between the IBM e-support infrastructure and the call home node of the current group. A proxy is used if the call home proxy settings are enabled. If the proxy setting is disabled, direct connections are attempted.; Note: This command can be executed only from the nodes that are a part of a currently existing call home group.

Exit status

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

Security

You must have root authority to run the mmcallhome 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.

Examples

To configure a call home group, issue this command:

mmcallhome group add group1 test-11 --node test-11,test-12,test-13

The system displays output similar to this:

Call home group group1 has been created

To view the configured call home groups, issue this command:

mmcallhome group list

The system displays output similar to this:


Call Home Group   Call Home Node   Call Home Child Nodes     
----------------- ---------------- ------------------------- 
group1            test-11          test-11,test-12,test-13

You can also give the same command with the --long option to view the configured call home groups with their long names:

mmcallhome group list --long

The system displays output similar to this:


Call Home Group   Call Home Node         Call Home Child Nodes                                            
----------------- ---------------------- --------------------------------------------- 
group1            test-11.localnet.com   test-11.localnet.com,test-12.localnet.com,
                                         test-13.localnet.com

To change customer information such as customer name, customer ID, and the country code, issue this command:

mmcallhome info change --customer-name "SpectrumScaleTest"
 --customer-id "1234" --country-code "JP"

The system displays output similar to this:


Success
Call home country-code has been set to JP
Call home customer-id has been set to 1234
Call home customer-name has been set to SpectrumScaleTest

To view the customer information, issue this command:

mmcallhome info list

The system displays output similar to this:


group      customerName       customerID    email   countryCode
-------- ------------------- ------------ --------- -------------
global     SpectrumScaleTest      1234      unknown      JP

To create a call home group automatically, issue this command:

mmcallhome group auto

The system displays output similar to this:


[I] Analysing the cluster...
[I] Creating <1> new call home groups:
[I] Call home child nodes = g5020-31.localnet.com,
    g5020-32.localnet.com,g5020-34.localnet.com
[I] Call home group autoGroup_1 has been created
[I] Nodes without call home: <1> (g5020-33.localnet.com)
[I] Updating call home node classes...
    g5020-32.localnet.com: 
    QOS configuration has been installed and broadcast to all nodes.
    g5020-32.localnet.com: 
    QOS configuration has been installed and broadcast to all nodes.
[I] The automatic group creation completed successfully.

To create a call home group automatically and enable the cluster for call home functionality by displaying options for acceptance, issue this command:

mmcallhome group auto --enable

The system displays output similar to this:


By accepting this request, you agree to allow
IBM and its subsidiaries to store and use your contact information and your
support information anywhere they do business worldwide. For more information,
please refer to the Program license agreement and documentation. If you agree,
please respond with "accept" for acceptance, else with "not accepted" to decline.
(accept / not accepted)
accept
[I] Analysing the cluster...
[I] Creating <1> new call home groups:
[I] Call home child nodes = g5020-31.localnet.com,
    g5020-32.localnet.com,g5020-34.localnet.com
[I] Call home group autoGroup_1 has been created
[I] Nodes without call home: <1> (g5020-33.localnet.com)
[I] Updating call home node classes...
g5020-32.localnet.com: QOS configuration has
been installed and broadcast to all nodes.
g5020-32.localnet.com: QOS configuration has
been installed and broadcast to all nodes.
[I] The automatic group creation completed successfully.
Call home enabled has been set to true

Additional messages:
License was accepted. Call home enabled.

Note: To accept the call home functionality, type accept manually. Type

mmcallhome group auto
--enable accept

to avoid the explicit acceptance from the user.

To use create new group after deleting the existing group, issue this command:

mmcallhome group auto --force

The system displays output similar to this:


[I] Analysing the cluster...
[I] Deleting old call home groups (--force mode)
[I] Creating <1> new call home groups:
[I] Call home child nodes = g5020-31.localnet.com,
    g5020-32.localnet.com,g5020-34.localnet.com
[I] Call home group autoGroup_1 has been created
[I] Nodes without call home: <1> (g5020-33.localnet.com)
[I] Updating call home node classes...
[I] The automatic group creation completed successfully.

To enable the call home service, issue this command:

mmcallhome capability enable

The system displays output similar to this:


By accepting this request, you agree to allow IBM 
and its subsidiaries to store and use your contact information and your support 
information anywhere they do business worldwide. For more information, 
please refer to the Program license agreement and documentation. 
If you agree, please respond with "accept" for acceptance, else with 
"not accepted" to decline.

(accept / not accepted)

accept
Call home enabled has been set to true

Additional messages:
License was accepted. Callhome enabled.

To register a daily task with cron, issue this command:
```
mmcallhome schedule add --task daily
```
The system displays output similar to this:
```
Call home daily has been set to enabled
```
To register a weekly task with cron, issue this command:
```
mmcallhome schedule add --task weekly
```
The system displays output similar to this:
```
Call home weekly has been set to enabled
```

To list the registered tasks for gather-send, issue this command:

mmcallhome schedule list

The system displays output similar to this:


=== List of registered schedule tasks ===

group     scheduleType   isEnabled    confFile
-------- -------------- ----------- -------------
global       daily         enabled    daily.conf
global       weekly        enabled    weekly.conf

To set the parameters for the proxy server, issue this command:

mmcallhome proxy change --proxy-location okapi --proxy-port 80 
--proxy-username root --proxy-password <password>

The system displays output similar to this:


Call home proxy-port has been set to 80
Call home proxy-username has been set to root
Call home proxy-password has been set to <password>
Call home proxy-location has been set to okapi

To view the proxy server parameters, issue this command:

mmcallhome proxy list

The system displays output similar to this:


group     proxyAuthEnabled  proxyEnabled   proxyLocation   proxyPort  proxyUsername
-------- ------------------ ------------- --------------  ----------- --------------
global         false             false         okapi           80          root

To invoke a one-time gather-send task, issue this command:
```
mmcallhome run GatherSend --task daily
```
The system displays output similar to this:
```
One time run completed with success
```

To run one-time send command to upload a file, issue this command:

mmcallhome run SendFile --file /ibm/gpfs0/testDir/testFile --desc MyTestData

The system displays output similar to this:


Running sendFile... (In case of network errors, it may take over 20 minutes for retries.)
Successfully uploaded the given file
Run mmcallhome status list --verbose to see the package name

To view the status of the currently running and the already completed call home tasks, issue this command:

mmcallhome status list

The system displays output similar to this:


=== Executed call home tasks ===
Group         Task         Start Time           Status
---------------------------------------------------------
autoGroup_1   daily        20181212021402.015   success
autoGroup_1   weekly       20181203110048.724   success
autoGroup_1   sendfile     20181203105920.936   success
autoGroup_1   SendPMRData  20181212141347.236   success

To test the connection, issue this command:

mmcallhome test connection

The system displays output similar to this:


Starting connectivity test between the call home node and IBM
Call home node: g5020-31.localnet.com
Starting time: Fri Aug 31 17:09:58 2018

Testing direct connection
------------------------------------------------------------
Testing <prefix Edge_SP_Config>:
Edge_SP_Config_1: 129.42.56.189 OK

Testing <prefix Edge_Profile>:
Edge_Profile_1: 129.42.56.189 OK

Testing <prefix Edge_Status_Report>:
Edge_Status_Report_1: 129.42.56.189 OK

------------------------------------------------------------
End time: Fri Aug 31 17:10:06 2018

Location

/usr/lpp/mmfs/bin

mmcallhome command

Synopsis

Availability

Description

Parameters

Exit status

Security

Examples

See also

Location