1# openbmctool Documentation
2
3This provides documentation beyond what is in the tool's help text.
4
5## Connecting to a system
6
7An IP address or hostname, password, and username are required for connecting to
8a BMC.
9
10These are passed in with the following options:
11
12- `-H`: The hostname or IP for the BMC
13- `-U`: The username One of the password options:
14- `-P`: The password, provided in-line
15- `-A`: Prompt for a password
16- `-E`: Take the password from envvar `OPENBMCTOOL_PASSWORD`
17
18## Enabling and Disabling Local BMC User Accounts
19
20The local user accounts on the BMC, such as root, can be disabled, queried, and
21re-enabled with the `local_users` sub-command.
22
23Important: After disabling local users, an LDAP user will need to be used for
24further interaction with the BMC, including if using openbmctool to enable local
25users again.
26
27To view current local user account status:
28
29```sh
30openbmctool <connection options> local_users queryenabled
31```
32
33To disable all local user accounts:
34
35```sh
36openbmctool <connection options> local_users disableall
37```
38
39To re-enable all local user accounts:
40
41```sh
42openbmctool <connection options> local_users enableall
43```
44
45## Remote logging via rsyslog
46
47The BMC has the ability to stream out local logs (that go to the systemd
48journal) via [rsyslog](https://www.rsyslog.com/).
49
50The BMC will send everything. Any kind of filtering and appropriate storage will
51have to be managed on the rsyslog server. Various examples are available on the
52internet. Here are few pointers:
53
54- <https://www.rsyslog.com/storing-and-forwarding-remote-messages/>
55- <https://www.rsyslog.com/doc/rsyslog%255Fconf%255Ffilter.html>
56- <https://www.thegeekdiary.com/understanding-rsyslog-filter-options/>
57
58### Configuring rsyslog server for remote logging
59
60```sh
61openbmctool <connection options> logging remote_logging_config -a <IP address> -p <port>
62```
63
64The IP address and port to be provided are of the remote rsyslog server. Once
65this command is run, the remote rsyslog server will start receiving logs from
66the BMC.
67
68Hostname can be specified instead of IP address, if DNS is configured on the
69BMC.
70
71### Disabling remote logging
72
73```sh
74openbmctool <connection options> logging remote_logging disable
75```
76
77It is recommended to disable remote logging before switching remote logging from
78an existing remote server to a new one (i.e before re-running the
79`remote_logging_config` option).
80
81### Querying remote logging config
82
83```sh
84openbmctool <connection options> logging remote_logging view
85```
86
87This will print out the configured remote rsyslog server's IP address and port,
88in JSON format.
89
90## BMC Certificate management
91
92Certificate management allows replacing the existing certificate and private key
93file with another (possibly certification Authority (CA) signed) certificate and
94private key file. Certificate management allows the user to install server,
95client and root certificates.
96
97### Update HTTPS server certificate
98
99```sh
100openbmctool <connection options> certificate update server https -f <File>
101```
102
103File: The [PEM](https://en.wikipedia.org/wiki/Privacy-Enhanced_Mail) file
104containing both certificate and private key.
105
106### Update LDAP client certificate
107
108```sh
109openbmctool <connection options> certificate update client ldap -f <File>
110```
111
112File: The PEM file containing both certificate and private key.
113
114### Update LDAP root certificate
115
116```sh
117openbmctool <connection options> certificate update authority ldap -f <File>
118```
119
120File: The PEM file containing only certificate.
121
122### Delete HTTPS server certificate
123
124```sh
125openbmctool <connection options> certificate delete server https
126```
127
128Deleting a certificate will create a new self-signed certificate and will
129install the same.
130
131### Delete LDAP client certificate
132
133```sh
134openbmctool <connection options> certificate delete client ldap
135```
136
137### Delete LDAP root certificate
138
139```sh
140openbmctool <connection options> certificate delete authority ldap
141```
142
143Deleting the root certificate can cause an LDAP service outage. Please refer to
144the LDAP documentation before using this command.
145
146## BMC LDAP Configuration
147
148In BMC, LDAP is used for remote authentication. BMC doesn't support remote
149user-management functionality.
150
151BMC supports secure/non-secure LDAP configuration.
152
153### Create LDAP Configuration
154
155#### NonSecure
156
157```sh
158openbmctool.py <connection options> ldap enable --uri="ldap://<ldap server IP/hostname>" --bindDN=<bindDN> --baseDN=<basDN> --bindPassword=<bindPassword> --scope="sub/one/base" --serverType="OpenLDAP/ActiveDirectory"
159```
160
161NOTE: configuring FQDN (fully qualified domain name/ hostname) in the "uri"
162parameter requires that DNS server be configured on the BMC.
163
164NOTE: Currently, openbmctool doesn't support configuring the DNS server on the
165BMC.
166
167#### Secure
168
169```sh
170openbmctool.py <connection options> ldap enable --uri="ldaps://<ldap server IP/hostname>" --bindDN=<bindDN> --baseDN=<basDN> --bindPassword=<bindPassword> --scope="sub/one/base" --serverType="OpenLDAP/ActiveDirectory"
171```
172
173NOTE: a) It is quite common to encounter the following error when running the
174openbmctool.py command string shown above:
175
176`xyz.openbmc_project.Common.Error.NoCACertificate`
177
178This error means that the BMC client needs to verify that the LDAP server's
179certificate has been signed by a known CA. The service action would be for the
180admin to upload the CA certificate to the BMC.
181
182To upload the CA certificate to the BMC, refer to the "Update LDAP root
183certificate" section of this document.
184
185b) openbmctool doesn't support individual LDAP config property update, To update
186a single property user need to recreate the LDAP config with the changed values.
187
188### Delete/Erase LDAP Configuration
189
190```sh
191openbmctool.py <connection options> ldap disable
192```
193
194NOTE: Make sure that root user is enabled before running the above command
195otherwise BMC would not be accessible.
196
197To enable root user, refer to the "To re-enable all local user accounts" section
198of this document.
199
200Currently openbmctool doesn't have support for specific user enablement.
201
202### Add privilege mapping
203
204```sh
205openbmctool.py <connection options> ldap privilege-mapper create --groupName=<groupName> --privilege="priv-admin/priv-user"
206```
207
208### Delete privilege mapping
209
210```sh
211openbmctool.py <connection options> ldap privilege-mapper delete --groupName=<groupName>
212```
213
214### List privilege mapping
215
216```sh
217openbmctool.py <connection options> ldap privilege-mapper list
218```
219
220The normal workflow for LDAP configuration would be as shown below
221
222- Configure the DNS server.
223- Configure LDAP. a) Configure CA certificate if secure LDAP server is being
224  configured. b) Create LDAP Configuration with local user.
225- Configure user privilege.
226
227NOTE:
228
229a) If a user tries to login with LDAP credentials and has not added the
230privilege mapping for the LDAP credentials then the user will get the following
231http error code and message.
232
233403, 'LDAP group privilege mapping does not exist'.
234
235Action: Add the privilege (refer to the section "Add privilege mapping")
236
237b) The following message may mean that the user lacks the required privileges on
238the BMC: "Insufficient Privilege"
239
240Action: Add the privilege (refer to the section "Add privilege mapping") with
241privilege=priv-admin
242
243c) Once LDAP is set up, openbmctool connection options work with both LDAP and
244local users.
245