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