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