1## Tools used in OpenBMC Test Automation ##
2
3## IPMItool considerations: ##
4
5IPMItool version 1.8.18 or later.
6```
7    $ ipmitool -V
8    ipmitool version 1.8.18
9```
10
11## Hardware Test Executive (HTX): ##
12
13HTX is a suite of test tools for stressing system hardware. It is routinely
14used by the test suites under `systest/`. Refer to [README](https://github.com/open-power/HTX)
15
16## Remote Logging via Rsyslog ##
17
18Refer to [README](https://github.com/openbmc/phosphor-logging/blob/master/README.md#remote-logging-via-rsyslog)
19
20## Converting SELs to readable format: ##
21
22Pre-requisite: A Power Linux system is required.
23
24* Obtain the SEL (System Error Log) parser tools:
25    - Go to https://openpower.xyz/job/openpower/job/openpower-op-build/
26    - Click the link for the BMC system of interest (e.g. witherspoon)
27    - Click the "host_fw_debug.tar" link in order to download the tar file.
28    - On your Power Linux system, untar the file with the following command:
29    ```
30    $ tar -xvf host_fw_debug.tar
31    ```
32
33    - Rename the untarred files with:
34    ```
35    $ for file_name in host_fw_debug* ; do mv $file_name ${file_name#host_fw_debug} ; done
36    ```
37
38    The files of interest are:
39    eSEL.pl
40    hbotStringFile
41    hbicore.syms
42
43* The error log binary parser is also required:
44    - Go to https://sourceforge.net/projects/linux-diag/files/ppc64-diag/
45    - Download the latest release version of the source tar zipped.
46    - Extract the tarball and compile. Refer to README in the source.
47    - On successful compilation, get `opal-elog-parse` binary.
48
49* To generate a readable error log from binary SEL data:
50
51   Create a directory and copy the binary files there.  Next,
52
53    ```
54    $ export PATH=$PATH:<path to directory>
55    ```
56   And run
57    ```
58    $ eSEL.pl -l SEL_data -p decode_obmc_data --op
59    ```
60    where `SEL_data` is the file containing SEL binary data and option "--op"
61    will refer "opal-elog-parse" instead or errl.
62
63    The output file `SEL_data.txt` contains the readable error log (SEL) data.
64
65
66## The opal-prd Tool: ##
67opal-prd is a tool used by the Energy Scale and RAS tests.  It should be
68installed on the OS of the system under test before running those tests.
69
70opal-prd may be installed on Ubuntu with:
71    ```
72    apt install opal-prd
73    ```
74    and on RedHat with:
75    ```
76    yum install opal-prd
77    ```
78
79
80## Obtain a copy of GitHub issues in CSV format: ##
81
82Note: You will be prompted to enter your GitHub password.
83
84Usage:
85```
86$ cd tools/
87$ python github_issues_to_csv <github user> <github repo>
88```
89Example for getting openbmc issues:
90```
91$ python github_issues_to_csv <github user>  openbmc/openbmc
92```
93Example for getting openbmc-test-automation issues:
94```
95$ python github_issues_to_csv <github user>  openbmc/openbmc-test-automation
96```
97
98
99## Generate Documentation for Robot Test Cases: ##
100
101Usage:
102```
103$ ./tools/generate_test_document <Robot test directory path> <test case document file path>
104```
105
106Example for generating tests cases documentation for tests directory:
107```
108$ ./tools/generate_test_document tests testsdirectoryTCdocs.html
109```
110
111Example for generating tests cases documentation:
112Note: Invoke the tool without arguments:
113```
114$ ./tools/generate_test_document
115```
116
117
118## Non-Volatile Memory Express Command Line Interface (nvme-cli): ##
119
120nvme-cli is a linux command line tool for accessing Non-Volatile Storage (NVM) media attached via PCIe bus.
121
122Source: https://github.com/linux-nvme/nvme-cli
123
124To install nvme-cli on RedHat:
125```
126yum install name-cli
127```
128To install nvme-cli on Ubuntu:
129```
130sudo apt-get install nvme-cli
131```
132
133* Obtaining the PPA for Ubuntu
134    - Add the sbates PPA to your sources: https://launchpad.net/~sbates/+archive/ubuntu/ppa
135
136
137## The Hdparm tool: ##
138
139hdparm is a command line utility for setting and viewing hardware parameters of hard disk drives.
140
141To install hdparm on RedHat:
142```
143yum install hdparm
144```
145To install hdparm on Ubuntu:
146```
147sudo apt-get update
148sudo apt-get install hdparm
149```
150
151## OpenSSL tool:
152OpenSSL is an open-source command line tool that is commonly used to generate certificates and private keys, create CSRs and identify certificate information.
153
154To generate a self-signed certificate with a private key:
155
156```
157openssl req -x509 -sha256 -newkey rsa:2048 -nodes -days <number of days a certificate is valid for> -keyout <certificate filename> -out <certificate filename> -subj "/O=<Organization Name>/CN=<Common Name>"
158```
159
160_Example:_
161```
162openssl req -x509 -sha256 -newkey rsa:2048 -nodes -days 365 -keyout certificate.pem -out certificate.pem -subj "/O=XYZ Corporation /CN=www.xyz.com"
163```
164
165To view installed certificates on a OpenBMC system:
166```
167openssl s_client -connect <BMC_IP>:443 -showcerts
168```
169
170Refer to the [OpenSSL manual](https://www.openssl.org/docs/manmaster/man1/req.html) for more details.
171
172## peltool: ##
173peltool is an open-source platform event log(PEL) tool generally used to view and delete pel logs that are generated on the BMC system. Also, provides various pel related operations as mentioned in the 'peltool --help'.
174
175```
176 peltool -h
177OpenBMC PEL Tool
178Usage: peltool [OPTIONS]
179
180Options:
181  --help                      Print this help message and exit
182  --file TEXT                 Display a PEL using its Raw PEL file
183  -i,--id TEXT                Display a PEL based on its ID
184  --bmc-id TEXT               Display a PEL based on its BMC Event ID
185  -a                          Display all PELs
186  -l                          List PELs
187  -n                          Show number of PELs
188  -r                          Reverse order of output
189  -h                          Include hidden PELs
190  -f,--info                   Include informational PELs
191  -t,--termination            List only critical system terminating PELs
192  -d,--delete TEXT            Delete a PEL based on its ID
193  -D,--delete-all             Delete all PELs
194  -s,--scrub TEXT             File containing SRC regular expressions to ignore
195  -x                          Display PEL(s) in hexdump instead of JSON
196  --archive                   List or display archived PELs
197```
198
199## guard tool: ##
200guard tool on BMC provides an option to create, view and delete the faulty units.
201Refer to [README](https://github.com/open-power/guard#readme)
202
203## pldmtool: ##
204pldmtool is an open-source client tool that acts as a PLDM requester which runs on the BMC. pldmtool supports the subcommands for PLDM types such as base, platform, bios, fru, and oem-ibm as mentioned in the 'pldmtool --help'.
205Refer to [README](https://github.com/openbmc/pldm/tree/master/pldmtool#README.md)
206