rack_tool(1)

Date

2021-06-25

Name

rack_tool - tool for doing operations related to one or more IPU-Machines in a rack

Synopsis

rack_tool.py [–version] [–help] <command> [<args>] [–ipum name bmc ip gw ip bmc username bmc password gw username gw password] [–config-file config file] [–global-credentials bmc username bmc password gw username gw password] [–log-dir log directory]
rack_tool.py upgrade [–help] [–golden] [–gw-root-overlay path to overlay]
rack_tool.py bist [–help]
rack_tool.py vipu-test [–help] [–vipu-path path to vipu binaries]
rack_tool.py status [–help] [–no-color]
rack_tool.py hostname [–help]
rack_tool.py install-key [–help]
rack_tool.py update-root-overlay [–help] [–overlay overlay directory]
rack_tool.py run-command [–help] -c command -d device
rack_tool.py bmc-factory-reset [–help]
rack_tool.py power-off [–help] [–hard]
rack_tool.py power-on [–help]
rack_tool.py power-cycle [–help]
rack_tool.py logging-server [–help] -a address -p port -d device

Description

rack_tool is a tool to make it easy to do operations related to all IPU-Machines in a rack.

Options

The options –ipum, –global-credentials and –config-file must go after the command parameters.

-v, –version

Print the version of the tool

-h, –help

Prints the synopsis and a list of all available commands. –help can also be given after a command to show individual help for each command.

–ipum name bmc ip gw ip bmc username bmc password gw username gw password
Option to manually define which IPU-Machines to perform operations on, instead of using a config file. Several IPU-Machines can be selected by passing the –ipum option multiple times.
Example:
rack_tool.py upgrade --ipum machine1 10.1.1.1 10.1.1.2 root password itadmin password
–global-credentials bmc username bmc password gw username gw password
Option to set a common set of login details for the IPU-Machines selected with –ipum option. If this option is used, the password and username parameters for the –ipum option can be omitted.
Example:
rack_tool.py upgrade --ipum machine1 10.1.1.1 10.1.1.2 --ipum machine2 10.1.2.1 10.1.2.2 --global-credentials root password itadmin password
–config-file config file
Config file with information about IPU-Machines to connect to. The config file will be ignored if the ‘–ipum’ parameter is given.
Example:
rack_tool.py upgrade --config-file /home/ipuuser/my_config_file.json
–log-dir log directory
Custom directory to write log files to.
Example:
rack_tool.py upgrade --log-dir /home/ipuuser/logs

Commands

upgrade

Start upgrade of IPU-Machines.

bist

Run built-in self test that checks that most components on the board are available and functional.

vipu-test

Run Virtual-IPU tests.

status

Show status of IPU-Machines in a rack.

hostname

Set hostname on GW and BMC.

install-key

Install the current user’s public SSH key to all IPU-Machines.

update-root-overlay

Copy all files in GW root overlay directory to all IPU-Machines

run-command

Run a command on a device (“bmc” or “gw”) on all IPU-Machines.

bmc-factory-reset

Do factory reset on the BMC on all IPU-Machines.

power-off

Power off GW and IPUs on all IPU-Machines

power-on

Power on GW and IPUs on all IPU-Machines

power-cycle

Power cycle GW and IPUs on all IPU-Machines

logging-server

Set logging server on a device (“bmc” or “gw”) on all IPU-Machines

Exit status

0 Successful program execution.
1 Unsuccessful program execution.

GW root overlay

This is a directory that contains all the files that should be copied to the GW after an upgrade. This makes it possible to create site-specific files that should be persistent on the GW after upgrade. The contents of this directory are copied over to the GW automatically if the location of this directory is given either as an object in the rack config file or as input parameter. The structure of the directory should be the same as the root directory on the GW.
An example of files that can be useful to have in the GW root overlay is files that relate to the outside world, such as NTP and syslog configuration files.

rack_config.json file format

rack_config.json is a JSON file that rack_tool uses to connect to all the IPU-Machines in a rack. It consists of one mandatory object “machines” and two optional objects “global_credentials” and “gw_root_overlay”. rack_tool will look for a config file in three different places with the following priority:
1. The file passed with the –config-file parameter.
2. A file named rack_config.json in the current working directory.
3. A rack_config.json file in the ~/.rack_tool/ directory
global_credentials

This is an object that holds the login details of the BMC and GW. the object has the following key/value pairs:

"global_credentials": {
    "bmc_username": "<username>",
    "bmc_passwd": "<password>",
    "gw_username": "<username>",
    "gw_passwd": "<password>"
}
gw_root_overlay

This object is a key/value pair that points to the location of the GW root overlay.

"gw_root_overlay": "/home/ipuuser/.rack_tool/root-overlay",
log_directory
This object is a key/value pair that points to the directory where logs should be stored. If this object is not present in the config file, rack_tool will place logs in the first of the following directories that it has write permission to:

  1. rack_tool_location/logs

  2. /var/log/rack_tool

  3. current_working_directory/rack_tool_logs

"log_directory": "/home/ipuuser/rack_tool_logs"
machines

This is an array of machine objects that holds information about each IPU-Machine in the rack. Each machine object consists of the following key/value pairs:

"machines": [
    {
        "name": "<machine name>",
        "sn": "<serial number>",
        "mac_bmc": "<mac address>",
        "mac_gw": "<mac address>",
        "bmc_ip": "<ip address>",
        "gw_ip": "<ip address>",
        "rnic_ip": "<ip address>"
    }
]

Files

~/.rack_tool/

This directory is the default location for configuration files.

~/.rack_tool/rack_config.json

This is the rack configuration file for the rack.

~/.rack_tool/root-overlay/

This is the default directory for GW root overlay files