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