mmcallhome command

Manages the call home operations.

Synopsis

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

mmcallhome group list

mmcallhome group delete GroupName

mmcallhome group auto  [[--server ServerName]...]

mmcallhome capability list

mmcallhome capability enable

mmcallhome capability disable

mmcallhome info list

mmcallhome info change --key value  [[--key value]...]

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

mmcallhome proxy disable

mmcallhome proxy list

mmcallhome proxy change --key value  [[--key value]...]

mmcallhome schedule list

mmcallhome schedule add --task { daily | weekly }

mmcallhome schedule delete --task { daily | weekly }

mmcallhome run GatherSend --task { daily | weekly }

mmcallhome run SendFile --file file [--desc text]

mmcallhome status  list  [ --task{ daily  | weekly  | sendfile}] [-n num][--verbose ]

mmcallhome status delete {--task{ daily | weekly | sendfile} | --startTime time |
           --startTimeBefore time | --all }

mmcallhome test connection

Availability

Available with IBM Spectrum Scale™ Standard Edition or higher.

Description

Use the mmcallhome command to configure, enable, run, schedule, and monitor call home related tasks in the GPFS™ cluster. The protocol functions provided in this command, or any similar command, are generally referred to as CES (Cluster Export Services). For example, protocol node and CES node are functionally equivalent terms.

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 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 will initiate the data collection from the call home child nodes and will upload data to IBM using HTTPS protocol. At least one call home group needs to be defined within IBM Spectrum Scale. 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 a IBM Spectrum Scale cluster.

For more information about the callhome feature, see "Understanding the call home functionality" in IBM Spectrum Scale: Advanced Administration Guide.

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

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.

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 program detects a server automatically.

If a proxy is needed, specify the proxy by using the mmcallhome proxy command.

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

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

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.

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.

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 one-time gather-send task to collect data and upload.

--task daily: Specifies the daily task that needs to be executed.

--task weekly: Specifies the weekly task that needs to be executed.

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 text]: 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: '-', '_', '.', ' ', ','

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.

--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 a system check to ensure that a connection is established:

connection: Specifies the connection to check.

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 file system in IBM Spectrum Scale: Administration and Programming Reference.

Examples

To configure a call home group, issue this command:

mmcallhome group add group1 themisto0 -N themisto0,themisto1,themisto2

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                     themisto0                themisto0,themisto1,themisto2

To change customer information such as customer name, customer ID, and the country code, issue this command:
```
mmcallhome info change --customer-name "SpectrumScaleTest" --customerid
"1234" --country-code "JP"
```
The system displays output similar to this:
```
Success
```

To view the customer information, issue this command:

mmcallhome info list

The system displays output similar to this:

Parameter                             Value
customer-name                         SpectrumScaleTest
customer-id                           1234
voice-phone
offshift-phone
modem-phone
modem-prefix
ign1phone
ign2phone
customer-location
email
special-instruction
callhome-method                       ethernet
remote-service-callback-number
country-code                          JP

To enable the call home service, issue this command:

mmcallhome capability enable

The system displays output similar to this:

Call home node: themisto0
Call home child nodes to collect data: themisto0 themisto1 themisto2 (total 3 nodes)
Excluded nodes:
SSH Access Check: OK
Data package directory: /tmp/mmfs/callhome
Success

To register a daily task with cron, issue this command:

mmcallhome schedule add --task daily

The system displays output similar to this:

/etc/cron.d/gpfscallhome_gatherSend_daily.conf registered
41 command entries are defined for this task

To register a weekly task with cron, issue this command:

mmcallhome schedule add --task weekly

The system displays output similar to this:

/etc/cron.d/gpfscallhome_gatherSend_weekly.conf registered
14 command entries are defined for this task

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

mmcallhome schedule list

The system displays output similar to this:

Registered Tasks for gatherSend:
ConfFile               CronParameters
daily.conf             3 2 * * *
weekly.conf            54 3 * * sun

To monitor the call home tasks, issue this command:

mmcallhome status list

The system displays output similar to this:

Task   Start time          Status        Package file name
daily  20150930132656.582  success       ...aultDaily.g_daily.20150930132656582.cl0.DC
daily  20150930133134.802  success       ...aultDaily.g_daily.20150930133134802.cl0.DC
daily  20150930133537.509  success       ...aultDaily.g_daily.20150930133537509.cl0.DC
daily  20150930133923.063  success       ...aultDaily.g_daily.20150930133923063.cl0.DC
RunSendFile 20150930133422.843 success
...group2.MyTestData.s_file.20150930133422843.cl0.DC

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

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

The system displays output similar to this:

Success

To view the proxy server parameters, issue this command:

mmcallhome proxy list

The system displays output similar to this:

Status
proxy-enabled         NO
proxy-auth-enabled    false
Parameter
proxy-location        okapi
proxy-port 80
proxy-username        root
proxy-password        xxxxx

To invoke a one-time gather-send task, issue this command:
```
mmcallhome run GatherSend --task daily
```
The system displays output similar to this:
```
Starting one time run using daily.conf
```

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.)
StartTime=20150930193046.693
Successfully uploaded the given file
Run mmcallhome status ls -v 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 --verbose

The system displays output similar to this: Start of change

Task Start time Updated time Status RC or Step
Package file name
[ additional info: value ]
--------------------------------------------------------------------------------
RunSendFile 20150930193046.693 20150930193059 success RC=0
11786648094375.4_2_0_0.1234.SpectrumScaleTest.group1.MyTestData.s_fil
e.20150930193046693.cl0.DC
Original file name: testFile
--------------------------------------------------------------------------------

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: themisto0
Starting time: Wed Sep 30 14:37:51 JST 2015
Testing connection via proxy server (no authentication required)
User: NA Pass: NA Host: okapi Port: 80
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

To check the version and the subversion of the mmcallhome program, issue this command:
```
mmcallhome version
```
The system displays output similar to this:
```
Version: 4.2.0-005
```

Location

/usr/lpp/mmfs/bin

mmcallhome command

Synopsis

Availability

Description

Parameters

Exit status

Security

Examples

See also

Location