mmcallhome command

Availability

Available with IBM Spectrum Scale™ Standard Edition or higher.

Description

By using this command, predefined data from each node can be collected on a regular basis 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 IBM Spectrum Scale 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 requires 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 that needs to keep all Linux nodes in one group and all AIX® nodes in the other group. The call home node needs to have access to the external network via port 443. The maximum number of nodes per group should not exceed 32. 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 a GPFS 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 which 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 GPFS cluster. If the number of nodes exceeds 32, the command will fail. When this parameter is omitted, only the call home node will be added to the child node. Additionally, call home node will be 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 recreating 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 a call home group.

--server ServerName

Specifies one or more call home servers. The server must be able to access the call home functionality through 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 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.

Note: If no --server (option) is specified, the system automatically identifies the possible call home node. If a proxy is defined and enabled in the global configuration, then the connection through proxy is used in identification of the possible call home node. If the proxy is disabled in the global configuration, then a direct connection from the nodes to the IBM EDGE server in the internet is used.

all

Specifies that each node is a call home server. This configuration avoids heavy work load for scheduled call home tasks on call home servers serving large groups. While using all option, it is recommended to use a proxy to access the internet.

Note: Multiple servers can be specified by repeating this option or by specifying a string, containing either a comma or a blank to separate the list of servers. If a group exists then the specified server must not be a member of that group. Each call home server must be able to access the internet either directly or via a proxy.

--force

Creates new groups after deleting the existing groups.

Note: If this option is defined and no server node has been specified, potential server nodes get detected automatically. If no server gets detected, an error is returned and the existing groups does not get deleted.

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

Note: It is not possible to use this option multiple times or together with the −−disable option.

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

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 Customer	E-mail ID of the customer. All alphanumeric and non-alphanumeric characters are supported.
country-code 2 alphabet ISO	Country code (Example, US)

proxy

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

enable

Enables proxy access.

[--with-proxy-auth]

Enables user ID and password authentication to the proxy server.

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, should 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 will be 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]

Specifies the dot-delimited PMR descriptor, where x, y and z could be digits, and y might additionally be a letter.

4

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]

Specifies the log of the daily or weekly task.

--task sendfile

Specifies the status of the tasks initiated by the "run sendfile" command.

[-n num]

Specifies the number of entry per gather-send task to show.

-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

Specifies additional information.

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

• Task: Name of the gather-send configuration file.
• Started time: Timestamp when the gather-send task is invoked.
• Updated time: Timestamp when the status is updated.
• Status: Success/minor error/failed/running.
• RC or Step: When the status is failed/success, the return code of the task is shown. See below for the return code description of the gather-send task. When the status is running, the step is shown. See below for the step description.
  • Package file name: Name of the created data package to upload.
  • additional info: Any additional info for the task.
  Gather-send task return codes:

  • 0 - Success
  • 1 - Successfully uploaded after a few send retries
  • 2 - Some gather commands failed but logs collected from all child nodes and successfully uploaded
  • 3 - Could not collect logs from some nodes but the call home node created the data package and successfully uploaded
  • 4 - Error in command parameter
  • 5 - Call home is disabled
  • 6 - Another gather-send task for the same configuration file is already running
  • 7 - Error in gather-send configuration file
  • 8 - Data package created but sender failed
  • 9 - Internal error
  • 10 - Critical error
  • 99 - Unknown
  Gather-send task steps:

  • step 1 - Initializing
  • step 2 - Each call home child nodes gathering logs
  • step 3 - Pulling log collection from child nodes
  • step 4 - Creating data package
  • step 5 - Calling send task
  • step 6 - Final status

delete

Deletes the status log of the specified configuration file with the following options:

--task [daily | weekly]

Specifies the log of the daily or weekly task.

--task sendfile

Specifies the log of the tasks initiated by the "run sendfile" command.

[-n num]

Specifies the number of entry per gather-send task to show.

--startTime starttime

Specifies the start time of the log to delete.

--startTimeBefore starttime

All logs older than the time specified by this option will be deleted..

--all

All logs will be 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 which 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.

See also

Location