Manage the ONTAP mediator service
Manage the ONTAP Mediator service, including changing user credentials, stopping and re-enabling the service, verifying its health, and installing or uninstalling SCST for host maintenance. You can also manage certificates, such as regenerating self-signed certificates, replacing them with trusted third-party certificates, and troubleshooting certificate-related issues.
Change the username
You can change the username using the following procedure.
Perform this task on the Linux host on which the ONTAP Mediator service is installed.
If you are unable to reach this command, you might need to run the command using the full path as shown in the following example:
/usr/local/bin/mediator_username
Change the username by choosing one of the following options:
-
Option (a): Run the command
mediator_change_user
and respond to the prompts as shown in the following example:[root@mediator-host ~]# mediator_change_user Modify the Mediator API username by entering the following values: Mediator API User Name: mediatoradmin Password: New Mediator API User Name: mediator The account username has been modified successfully. [root@mediator-host ~]#
-
Option (b): Run the following command:
MEDIATOR_USERNAME=mediator MEDIATOR_PASSWORD=mediator2 MEDIATOR_NEW_USERNAME=mediatoradmin mediator_change_user
[root@mediator-host ~]# MEDIATOR_USERNAME=mediator MEDIATOR_PASSWORD='mediator2' MEDIATOR_NEW_USERNAME=mediatoradmin mediator_change_user The account username has been modified successfully. [root@mediator-host ~]#
Change the password
You can change the password using the following procedure.
Perform this task on the Linux host on which the ONTAP Mediator service is installed.
If you are unable to reach this command, you might need to run the command using the full path as shown in the following example:
/usr/local/bin/mediator_change_password
Change the password by choosing one of the following options:
-
Option (a): Run the
mediator_change_password
command and respond to the prompts as shown in the following example:[root@mediator-host ~]# mediator_change_password Change the Mediator API password by entering the following values: Mediator API User Name: mediatoradmin Old Password: New Password: Confirm Password: The password has been updated successfully. [root@mediator-host ~]#
-
Option (b): Run the following command:
MEDIATOR_USERNAME=mediatoradmin MEDIATOR_PASSWORD=mediator1 MEDIATOR_NEW_PASSWORD=mediator2 mediator_change_password
The example shows that the password is changed from "mediator1" to "mediator2".
[root@mediator-host ~]# MEDIATOR_USERNAME=mediatoradmin MEDIATOR_PASSWORD=mediator1 MEDIATOR_NEW_PASSWORD=mediator2 mediator_change_password The password has been updated successfully. [root@mediator-host ~]#
Stop the ONTAP Mediator service
To stop the ONTAP Mediator service, perform the following steps:
-
Stop the ONTAP Mediator:
systemctl stop ontap_mediator
-
Stop SCST:
systemctl stop mediator-scst
-
Disable the ONTAP Mediator and SCST:
systemctl diable ontap_mediator mediator-scst
Re-enable the ONTAP Mediator service
To re-enable the ONTAP Mediator service, perform the following steps:
-
Enable the ONTAP Mediator and SCST:
systemctl enable ontap_mediator mediator-scst
-
Start SCST:
systemctl start mediator-scst
-
Start ONTAP Mediator:
systemctl start ontap_mediator
Verify the ONTAP Mediator is healthy
After the ONTAP Mediator has been installed, you should verify that the ONTAP Mediator services are running.
-
View the status of the ONTAP Mediator services:
-
systemctl status ontap_mediator
[root@scspr1915530002 ~]# systemctl status ontap_mediator ontap_mediator.service - ONTAP Mediator Loaded: loaded (/etc/systemd/system/ontap_mediator.service; enabled; vendor preset: disabled) Active: active (running) since Mon 2022-04-18 10:41:49 EDT; 1 weeks 0 days ago Process: 286710 ExecStop=/bin/kill -s INT $MAINPID (code=exited, status=0/SUCCESS) Main PID: 286712 (uwsgi) Status: "uWSGI is ready" Tasks: 3 (limit: 49473) Memory: 139.2M CGroup: /system.slice/ontap_mediator.service ├─286712 /opt/netapp/lib/ontap_mediator/pyenv/bin/uwsgi --ini /opt/netapp/lib/ontap_mediator/uwsgi/ontap_mediator.ini ├─286716 /opt/netapp/lib/ontap_mediator/pyenv/bin/uwsgi --ini /opt/netapp/lib/ontap_mediator/uwsgi/ontap_mediator.ini └─286717 /opt/netapp/lib/ontap_mediator/pyenv/bin/uwsgi --ini /opt/netapp/lib/ontap_mediator/uwsgi/ontap_mediator.ini [root@scspr1915530002 ~]#
-
systemctl status mediator-scst
[root@scspr1915530002 ~]# systemctl status mediator-scst Loaded: loaded (/etc/systemd/system/mediator-scst.service; enabled; vendor preset: disabled) Active: active (running) since Mon 2022-04-18 10:41:47 EDT; 1 weeks 0 days ago Process: 286595 ExecStart=/etc/init.d/scst start (code=exited, status=0/SUCCESS) Main PID: 286662 (iscsi-scstd) Tasks: 1 (limit: 49473) Memory: 1.2M CGroup: /system.slice/mediator-scst.service └─286662 /usr/local/sbin/iscsi-scstd [root@scspr1915530002 ~]#
-
-
Confirm the ports that are used by the ONTAP Mediator service:
netstat
[root@scspr1905507001 ~]# netstat -anlt | grep -E '3260|31784' tcp 0 0 0.0.0.0:31784 0.0.0.0:* LISTEN tcp 0 0 0.0.0.0:3260 0.0.0.0:* LISTEN tcp6 0 0 :::3260 :::* LISTEN
Manually uninstall SCST to perform host maintenance
To uninstall SCST, you need the SCST tar bundle that is used for the installed version of ONTAP Mediator.
-
Download the appropriate SCST bundle (as shown in the following table) and untar it.
For this version …
Use this tar bundle…
ONTAP Mediator 1.9
scst-3.8.0.tar.bz2
ONTAP Mediator 1.8
scst-3.8.0.tar.bz2
ONTAP Mediator 1.7
scst-3.7.0.tar.bz2
ONTAP Mediator 1.6
scst-3.7.0.tar.bz2
ONTAP Mediator 1.5
scst-3.6.0.tar.bz2
ONTAP Mediator 1.4
scst-3.6.0.tar.bz2
ONTAP Mediator 1.3
scst-3.5.0.tar.bz2
ONTAP Mediator 1.1
scst-3.4.0.tar.bz2
ONTAP Mediator 1.0
scst-3.3.0.tar.bz2
-
Issue the following commands in the "scst" directory:
-
systemctl stop mediator-scst
-
make scstadm_uninstall
-
make iscsi_uninstall
-
make usr_uninstall
-
make scst_uninstall
-
depmod
-
Manually install SCST to perform host maintenance
To manually install SCST, you need the SCST tar bundle that is used for the installed version of ONTAP Mediator (see the table above).
-
Issue the following commands in the "scst" directory:
-
make 2release
-
make scst_install
-
make usr_install
-
make iscsi_install
-
make scstadm_install
-
depmod
-
cp scst/src/certs/scst_module_key.der /opt/netapp/lib/ontap_mediator/ontap_mediator/SCST_mod_keys/
-
patch /etc/init.d/scst < /opt/netapp/lib/ontap_mediator/systemd/scst.patch
-
-
Optionally, if Secure Boot is enabled, before you reboot, perform the following steps:
-
Determine each file name for "scst_vdisk", "scst", and "iscsi_scst" modules:
[root@localhost ~]# modinfo -n scst_vdisk [root@localhost ~]# modinfo -n scst [root@localhost ~]# modinfo -n iscsi_scst
-
Determine the kernel release:
[root@localhost ~]# uname -r
-
Sign each file with the kernel:
[root@localhost ~]# /usr/src/kernels/<KERNEL-RELEASE>/scripts/sign-file \sha256 \ /opt/netapp/lib/ontap_mediator/ontap_mediator/SCST_mod_keys/scst_module_key.priv \ /opt/netapp/lib/ontap_mediator/ontap_mediator/SCST_mod_keys/scst_module_key.der \ _module-filename_
-
Install the correct key with the UEFI firmware.
Instructions for installing the UEFI key are located at:
/opt/netapp/lib/ontap_mediator/ontap_mediator/SCST_mod_keys/README.module-signing
The generated UEFI key is located at:
/opt/netapp/lib/ontap_mediator/ontap_mediator/SCST_mod_keys/scst_module_key.der
-
-
Perform a reboot:
reboot
Uninstall the ONTAP Mediator service
If necessary, you can remove the ONTAP Mediator service.
The ONTAP Mediator must be disconnected from ONTAP before you remove the ONTAP Mediator service.
You need to perform this task on the Linux host on which the ONTAP Mediator service is installed.
If you are unable to reach this command, you might need to run the command using the full path as shown in the following example:
/usr/local/bin/uninstall_ontap_mediator
-
Uninstall the ONTAP Mediator service:
uninstall_ontap_mediator
[root@mediator-host ~]# uninstall_ontap_mediator ONTAP Mediator: Self Extracting Uninstaller + Removing ONTAP Mediator. (Log: /tmp/ontap_mediator.GmRGdA/uninstall_ontap_mediator/remove.log) + Remove successful. [root@mediator-host ~]#
Regenerate a temporary self-signed certificate
Beginning with ONTAP Mediator 1.7, you can regenerate a temporary self-signed certificate using the following procedure.
This procedure is only supported on systems running ONTAP Mediator 1.7 or later. |
-
You perform this task on the Linux host on which the ONTAP Mediator service is installed.
-
You can perform this task only if the generated self-signed certificates have become obsolete due to changes to the hostname or IP address of the host after installing the ONTAP Mediator.
-
After the temporary self-signed certificate has been replaced by a trusted third-party certificate, you do not use this task to regenerate a certificate. The absence of a self-signed certificate will cause this procedure to fail.
To regenerate a new temporary self-signed certificate for the current host, perform the following step:
-
Restart the ONTAP Mediator service:
./make_self_signed_certs.sh overwrite
[root@xyz000123456 ~]# cd /opt/netapp/lib/ontap_mediator/ontap_mediator/server_config [root@xyz000123456 server_config]# ./make_self_signed_certs.sh overwrite Adding Subject Alternative Names to the self-signed server certificate # # OpenSSL example configuration file. Generating self-signed certificates Generating RSA private key, 4096 bit long modulus (2 primes) ..................................................................................................................................................................++++ ........................................................++++ e is 65537 (0x010001) Generating a RSA private key ................................................++++ .............................................................................................................................................++++ writing new private key to 'ontap_mediator_server.key' ----- Signature ok subject=C = US, ST = California, L = San Jose, O = "NetApp, Inc.", OU = ONTAP Core Software, CN = ONTAP Mediator, emailAddress = support@netapp.com Getting CA Private Key
Replace self-signed certificates with trusted third-party certificates
If supported, you can replace self-signed certificates with trusted third-party certificates.
|
-
You perform this task on the Linux host on which the ONTAP Mediator service is installed.
-
You can perform this task if the generated self-signed certificates need to be replaced by certificates obtained from a trusted subordinate certificate authority (CA). To accomplish this, you should have access to a trusted public-key infrastructure (PKI) authority.
-
The following image shows the purposes of each ONTAP Mediator certificate.
-
The following image shows configuration for the web server setup and ONTAP Mediator server setup.
Step 1: Obtain a certificate from a third-party issuing a CA certificate
You can obtain a certificate from a PKI authority using the following procedure.
The following example demonstrates replacing the self-signed certificate actors, namely ca.key
, ca.csr
, ca.srl
, and ca.crt
located at /opt/netapp/lib/ontap_mediator/ontap_mediator/server_config/
with the third-party certificate actors.
The example illustrates the criteria necessary for the certificates required for the ONTAP Mediator service. You can obtain the certificates from a PKI authority in a way that might be different to this procedure. Adjust the procedure as per your business need. |
-
Create a private key
ca.key
and a configuration fileopenssl_ca.cnf
that will be consumed by the PKI authority to generate a certificate.-
Generate the private key
ca.key
:Example
openssl genrsa -aes256 -out ca.key 4096
-
The configuration file
openssl_ca.cnf
(located at/opt/netapp/lib/ontap_mediator/ontap_mediator/server_config/openssl_ca.cnf
) defines the properties that the generated certificate must have.
-
-
Use the private key and configuration file to create a certificate signing request
ca.csr
:Example:
openssl req -key <private_key_name>.key -new -out <certificate_csr_name>.csr -config <config_file_name>.cnf
[root@scs000216655 server_config]# openssl req -key ca.key -new -config openssl_ca.cnf -out ca.csr Enter pass phrase for ca.key: [root@scs000216655 server_config]# cat ca.csr -----BEGIN CERTIFICATE REQUEST----- MIIE6TCCAtECAQAwgaMxCzAJBgNVBAYTAlVTMRMwEQYDVQQIDApDYWxpZm9ybmlh ... erARKhY9z0e8BHPl3g== -----END CERTIFICATE REQUEST-----
-
Send the certificate signing request
ca.csr
to a PKI authority for their signature.The PKI authority verifies the request and signs the
.csr
, generating the certificateca.crt
. Additionally, you need to obtain theroot_ca.crt
certificate that signed theca.crt
certificate from the PKI authority.For SnapMirror Business Continuity (SM-BC) clusters, you must add the ca.crt
androot_ca.crt
certificates to an ONTAP cluster. See Configure the ONTAP Mediator and clusters for SnapMirror active sync.
Step 2: Generate a server certificate by signing with a third-party CA certification
A server certificate must be signed by the private key ca.key
and the third-party certificate ca.crt
. Additionally, the configuration file /opt/netapp/lib/ontap_mediator/ontap_mediator/server_config/openssl_server.cnf
contains certain attributes that specify the properties required for server certificates issued by OpenSSL.
The following commands can generate a server certificate.
-
To generate a server certificate signing request (CSR), run the following command from the
/opt/netapp/lib/ontap_mediator/ontap_mediator/server_config
folder:openssl req -config openssl_server.cnf -extensions v3_req -nodes -newkey rsa:4096 -sha512 -keyout ontap_mediator_server.key -out ontap_mediator_server.csr
-
To generate a server certificate from the CSR, run the following command from the
/opt/netapp/lib/ontap_mediator/ontap_mediator/server_config
folder:The ca.crt
andca.key
files were obtained from a PKI authority. If you are using a different certificate name, for example,intermediate.crt
andintermediate.key
, replaceca.crt
andca.key
withintermediate.crt
andintermediate.key
respectively.openssl x509 -extfile openssl_server.cnf -extensions v3_req -CA ca.crt -CAkey ca.key -CAcreateserial -sha512 -days 1095 -req -in ontap_mediator_server.csr -out ontap_mediator_server.crt
-
The
-CAcreateserial
option is used to generate theca.srl
orintermediate.srl
files, depending on the certificate name that you are using.
-
Step 3: Replace new third-party CA certificate and server certificate in ONTAP Mediator configuration
The certificate configuration is supplied to the ONTAP Mediator service in the configuration file located at /opt/netapp/lib/ontap_mediator/ontap_mediator/server_config/ontap_mediator.config.yaml
. The file includes the following attributes:
cert_path: '/opt/netapp/lib/ontap_mediator/ontap_mediator/server_config/ontap_mediator_server.crt' key_path: '/opt/netapp/lib/ontap_mediator/ontap_mediator/server_config/ontap_mediator_server.key' ca_cert_path: '/opt/netapp/lib/ontap_mediator/ontap_mediator/server_config/ca.crt' ca_key_path: '/opt/netapp/lib/ontap_mediator/ontap_mediator/server_config/ca.key' ca_serial_path: '/opt/netapp/lib/ontap_mediator/ontap_mediator/server_config/ca.srl'
-
cert_path
andkey_path
are server certificate variables. -
ca_cert_path
,ca_key_path
, andca_serial_path
are CA certificate variables.
-
Replace all
ca.*
files with the third-party certificates. -
Create a certificate chain from the
ca.crt
andontap_mediator_server.crt
certificates:cat ontap_mediator_server.crt ca.crt > ontap_mediator_server_chain.crt
-
Update the
/opt/netapp/lib/ontap_mediator/uwsgi/ontap_mediator.ini
file.Update the values of
mediator_cert
,mediator_key
, andca_certificate
:set-placeholder = mediator_cert = /opt/netapp/lib/ontap_mediator/ontap_mediator/server_config/ontap_mediator_server_chain.crt
set-placeholder = mediator_key = /opt/netapp/lib/ontap_mediator/ontap_mediator/server_config/ontap_mediator_server.key
set-placeholder = ca_certificate = /opt/netapp/lib/ontap_mediator/ontap_mediator/server_config/root_ca.crt
-
The
mediator_cert
value is the path of theontap_mediator_server_chain.crt
file. -
The
mediator_key value
is the key path in theontap_mediator_server.crt
file, which isontap_mediator_server.key
. -
The
ca_certificate
value is the path of theroot_ca.crt
file.
-
-
Verify that the following attributes of the newly generated certificates are set correctly:
-
Linux Group Owner:
netapp:netapp
-
Linux permissions:
600
-
-
Restart the ONTAP Mediator:
systemctl restart ontap_mediator
Step 4: Optionally, use a different path or name for your third-party certificates
You can use third-party certificates with a different name other than ca.*
or store the third-party certificates in a different location.
-
Configure the
/opt/netapp/lib/ontap_mediator/ontap_mediator/server_config/ontap_mediator.user_config.yaml
file to override the default variable values in theontap_mediator.config.yaml
file.If you obtained
intermediate.crt
from a PKI authority and you store its private keyintermediate.key
at the location/opt/netapp/lib/ontap_mediator/ontap_mediator/server_config
, theontap_mediator.user_config.yaml
file should look like the following example:If you used intermediate.crt
to sign theontap_mediator_server.crt
certificate, theintermediate.srl
file is generated. See Step 2: Generate a server certificate by signing with a third-party CA certification for more information.[root@scs000216655 server_config]# cat ontap_mediator.user_config.yaml # This config file can be used to override the default settings in ontap_mediator.config.yaml # To override a setting, copy the property key from ontap_mediator.config.yaml to this file and # set the property to the desired value. e.g., # # The default value for 'default_mailboxes_per_target' is 4 in ontap_mediator.config.yaml # # To override this value with 6 mailboxes per target, add the following key/value pair # below this comment: # # 'default_mailboxes_per_target': 6 # cert_path: '/opt/netapp/lib/ontap_mediator/ontap_mediator/server_config/ontap_mediator_server.crt' key_path: '/opt/netapp/lib/ontap_mediator/ontap_mediator/server_config/ontap_mediator_server.key' ca_cert_path: '/opt/netapp/lib/ontap_mediator/ontap_mediator/server_config/intermediate.crt' ca_key_path: '/opt/netapp/lib/ontap_mediator/ontap_mediator/server_config/intermediate.key' ca_serial_path: '/opt/netapp/lib/ontap_mediator/ontap_mediator/server_config/intermediate.srl'
-
If you are using a certificate structure where the
root_ca.crt
certificate provides anintermediate.crt
certificate that signs theontap_mediator_server.crt
certificate, create a certificate chain from theintermediate.crt
andontap_mediator_server.crt
certificates:You should have obtained the intermediate.crt
andontap_mediator_server.crt
certificates from a PKI authority earlier in the procedure.cat ontap_mediator_server.crt intermediate.crt > ontap_mediator_server_chain.crt
-
Update the
/opt/netapp/lib/ontap_mediator/uwsgi/ontap_mediator.ini
file.Update the values of
mediator_cert
,mediator_key
, andca_certificate
:set-placeholder = mediator_cert = /opt/netapp/lib/ontap_mediator/ontap_mediator/server_config/ontap_mediator_server_chain.crt
set-placeholder = mediator_key = /opt/netapp/lib/ontap_mediator/ontap_mediator/server_config/ontap_mediator_server.key
set-placeholder = ca_certificate = /opt/netapp/lib/ontap_mediator/ontap_mediator/server_config/root_ca.crt
-
The
mediator_cert
value is the path of theontap_mediator_server_chain.crt
file. -
The
mediator_key
value is the key path in theontap_mediator_server.crt
file, which isontap_mediator_server.key
. -
The
ca_certificate
value is the path of theroot_ca.crt
file.For SnapMirror Business Continuity (SM-BC) clusters, you must add the intermediate.crt
androot_ca.crt
certificates to an ONTAP cluster. See Configure the ONTAP Mediator and clusters for SnapMirror active sync.
-
-
Verify that the following attributes of the newly generated certificates are set correctly:
-
Linux Group Owner:
netapp:netapp
-
Linux permissions:
600
-
-
-
Restart the ONTAP Mediator when the certificates are updated in the configuration file:
systemctl restart ontap_mediator
Troubleshoot certificate-related issues
You can check certain properties of the certificates.
Verify certificate expiration
Use the following command to identify the certificate validity range:
[root@scs000216982 server_config]# openssl x509 -in ca.crt -text -noout Certificate: Data: ... Validity Not Before: Feb 22 19:57:25 2024 GMT Not After : Feb 15 19:57:25 2029 GMT
Verify X509v3 extensions in CA certification
Use the following command to verify the X509v3 extensions in the CA certification.
The properties defined within v3_ca
in openssl_ca.cnf
are displayed as X509v3 extensions
in ca.crt
.
[root@scs000216982 server_config]# pwd /opt/netapp/lib/ontap_mediator/ontap_mediator/server_config [root@scs000216982 server_config]# cat openssl_ca.cnf ... [ v3_ca ] subjectKeyIdentifier = hash authorityKeyIdentifier = keyid:always,issuer basicConstraints = critical, CA:true keyUsage = critical, cRLSign, digitalSignature, keyCertSign [root@scs000216982 server_config]# openssl x509 -in ca.crt -text -noout Certificate: Data: ... X509v3 extensions: X509v3 Subject Key Identifier: 9F:06:FA:47:00:67:BA:B2:D4:82:70:38:B8:48:55:B5:24:DB:FC:27 X509v3 Authority Key Identifier: keyid:9F:06:FA:47:00:67:BA:B2:D4:82:70:38:B8:48:55:B5:24:DB:FC:27 X509v3 Basic Constraints: critical CA:TRUE X509v3 Key Usage: critical Digital Signature, Certificate Sign, CRL Sign
Verify X509v3 extensions in server certificate and subject Alt Names
The v3_req
properties defined in the openssl_server.cnf
configuration file are displayed as X509v3 extensions
in the certificate.
In the following example, you can obtain the variables in the alt_names
sections by running the commands hostname -A
and hostname -I
on the Linux VM on which the ONTAP Mediator is installed.
Check with your network administrator for the correct values of the variables.
[root@scs000216982 server_config]# pwd /opt/netapp/lib/ontap_mediator/ontap_mediator/server_config [root@scs000216982 server_config]# cat openssl_server.cnf ... [ v3_req ] basicConstraints = CA:false extendedKeyUsage = serverAuth keyUsage = keyEncipherment, dataEncipherment subjectAltName = @alt_names [ alt_names ] DNS.1 = abc.company.com DNS.2 = abc-v6.company.com IP.1 = 1.2.3.4 IP.2 = abcd:abcd:abcd:abcd:abcd:abcd [root@scs000216982 server_config]# openssl x509 -in ca.crt -text -noout Certificate: Data: ... X509v3 extensions: X509v3 Basic Constraints: CA:FALSE X509v3 Extended Key Usage: TLS Web Server Authentication X509v3 Key Usage: Key Encipherment, Data Encipherment X509v3 Subject Alternative Name: DNS:abc.company.com, DNS:abc-v6.company.com, IP Address:1.2.3.4, IP Address:abcd:abcd:abcd:abcd:abcd:abcd
Verify that a private key matches with a certificate
You can verify whether a particular private key matches with a certificate.
Use the following OpenSSL commands on the key and certificate respectively:
[root@scs000216982 server_config]# openssl rsa -noout -modulus -in intermediate.key | openssl md5 Enter pass phrase for intermediate.key: (stdin)= 14c6b98b0c7c59012b1de89eee4a9dbc [root@scs000216982 server_config]# openssl x509 -noout -modulus -in intermediate.crt | openssl md5 (stdin)= 14c6b98b0c7c59012b1de89eee4a9dbc
If the -modulus
attribute for both match, it indicates that the private key and certificate pair are compatible and can work with each other.
Verify that a server certificate is created from a particular CA certificate
You can use the following command to verify that the server certificate is created from a particular CA certificate.
[root@scs000216982 server_config]# openssl verify -CAfile ca.crt ontap_mediator_server.crt ontap_mediator_server.crt: OK
If the Online Certificate Status Protocol (OCSP) validation is being used, use the command openssl-verify.