Jump to contentJump to page navigation: previous page [access key p]/next page [access key n]
Applies to SUSE Enterprise Storage 6

13 Manual Configuration Edit source

This section introduces advanced information for users that prefer configuring dashboard's settings manually on the command line.

13.1 TLS/SSL Support Edit source

All HTTP connections to the dashboard are secured with SSL/TLS by default. A secure connection requires an SSL certificate. You can either use a self-signed certificate, or generate a certificate and have a well known certificate authority (CA) sign it.

Tip
Tip: Disabling SSL

You may want to disable the SSL support for a specific reason. For example, if the dashboard is running behind a proxy that does not support SSL.

Use caution when disabling SSL as user names and passwords will be sent to the dashboard unencrypted.

To disable SSL, run:

cephadm@adm > ceph config set mgr mgr/dashboard/ssl false
Tip
Tip: Restart Ceph Manager Processes

You need to restart the Ceph Manager processes manually after changing the SSL certificate and key. You can do so by either running

cephadm@adm > ceph mgr failACTIVE-MANAGER-NAME

or by disabling and re-enabling the dashboard module, which also triggers the manager to respawn itself:

cephadm@adm > ceph mgr module disable dashboard
cephadm@adm > ceph mgr module enable dashboard

13.1.1 Self-signed Certificates Edit source

Creating a self-signed certificate for secure communication is simple. This way you can get the dashboard running quickly.

Note
Note: Web Browsers Complain

Most Web browsers will complain about a self-signed certificate and require explicit confirmation before establishing a secure connection to the dashboard.

To generate and install a self-signed certificate, use the following built-in command:

cephadm@adm > ceph dashboard create-self-signed-cert

13.1.2 Self-signed or Trusted Third-party Certificate with OpenSSL Edit source

OpenSSL is an open-source command-line tool that is commonly used to generate private keys, create Certificate Signing Requests (CSR), install your SSL/TLS certificate, and identify certificate information. The following instructions illustrate how to generate a self-signed or trusted third-party certificate using OpenSSL:

  1. Generate a Private Key:

    cephadm@adm > openssl genrsa -des3 -out server.key 2048

    Type the passphrase to protect the key.

  2. Generate a CSR:

    cephadm@adm > openssl req -new -key server.key -out server.csr

    Enter the passphrase, and fill in the Country Name, State or Province Name, Locality Name, Organization Name, Organizational Unit Name, Common Name, Email Address.

    Note
    Note

    The Common Name should be the FQDN of the server. For example, server.mydomain.com.

    When asked for a challenge password and optional company name, leave it blank.

  3. To sign the certificate, select from the following options:

    • Trusted Third-party Certificate Authority.  Send the CSR to the third party for their signing. The following files should be received: Server certificate (public key) and the Intermediate CA and the bundles that chain to the Trusted Root CA.

    • Self-signed.  Sign the certificate with OpenSSL:

      openssl x509 -req -days 730 -in server.csr -signkey server.key -out server.crt

      Increase or decrease the value 730 as needed. This is the number of days for which the certificate is valid.

  4. (Optional) If needed, create a concatenated PEM file:

    cephadm@adm > openssl req -newkey rsa:2048 -new -nodes -x509 -days 3650 -keyout key.pem -out cert.pem

13.1.3 Certificates Signed by CA Edit source

To properly secure the connection to the dashboard and to eliminate Web browser complaints about a self-signed certificate, we recommend using a certificate that is signed by a CA.

You can generate a certificate key pair with a command similar to the following:

root # openssl req -new -nodes -x509 \
  -subj "/O=IT/CN=ceph-mgr-dashboard" -days 3650 \
  -keyout dashboard.key -out dashboard.crt -extensions v3_ca

The above command outputs dashboard.key and dashboard.crt files. After you get the dashboard.crt file signed by a CA, enable it for all Ceph Manager instances by running the following commands:

cephadm@adm > ceph config-key set mgr/dashboard/crt -i dashboard.crt
cephadm@adm > ceph config-key set mgr/dashboard/key -i dashboard.key
Tip
Tip: Different Certificates for Each Manager Instance

If you require different certificates for each Ceph Manager instance, modify the commands and include the name of the instance as follows. Replace NAME with the name of the Ceph Manager instance (usually the related host name):

cephadm@adm > ceph config-key set mgr/dashboard/NAME/crt -i dashboard.crt
cephadm@adm > ceph config-key set mgr/dashboard/NAME/key -i dashboard.key

13.1.4 Certificates Signed with a Custom CA Edit source

The following procedure needs to be followed once to create the root CA.

Note
Note

This is the key used to sign the certificate requests. Anyone holding this can sign certificates on your behalf.

  1. Create the Root Key:

    cephadm@adm > openssl genrsa -des3 -out rootCA.key 4096
    Note
    Note

    If you want a non-password protected key, remove the -des3 option.

  2. Create and self-sign the root certificate:

    cephadm@adm > openssl req -x509 -new -nodes -key rootCA.key -sha256 -days 1024 -out rootCA.crt

The following procedure needs to be followed for each server that needs a trusted certificate from our CA.

  1. Create the certificate key:

    cephadm@adm > openssl genrsa -out mydomain.com.key 2048

    The certificate signing request is where you specify the details for the certificate you want to generate. This request is processed by the owner of the Root Key to generate the certificate.

  2. These are two ways to create the CSR:

    Important
    Important

    When creating the certificate signing request, it is important to specify the Common Name providing the IP address or domain name for the service, otherwise the certificate cannot be verified.

    • Interactive method. For example:

      cephadm@adm > openssl req -new -key mydomain.com.key -out mydomain.com.csr

      You will then be prmopted for information. For example, the Country Name, Organization Name, and Email Address.

    • One-liner method. This is where instead of being interactively prompted, you include the information up front. For example:

      cephadm@adm > openssl req -new -sha256 -key mydomain.com.key -subj "/C=US/ST=CA/O=MyOrg, Inc./CN=mydomain.com" -out mydomain.com.csr

      If you need to pass additional configuration in the one-liner method, you can use the -config parameter. For example:

      cephadm@adm > openssl req -new -sha256 \
            -key mydomain.com.key \
            -subj "/C=US/ST=CA/O=MyOrg, Inc./CN=mydomain.com" \
            -reqexts SAN \
            -config <(cat /etc/ssl/openssl.cnf \
                <(printf "\n[SAN]\nsubjectAltName=DNS:mydomain.com,DNS:www.mydomain.com")) \
            -out mydomain.com.csr
  3. Verify the CSR content:

    cephadm@adm > openssl req -in mydomain.com.csr -noout -text
  4. Generate the certificate using the mydomain CSR and key along with the CA Root Key:

    cephadm@adm > openssl x509 -req -in mydomain.com.csr -CA rootCA.crt -CAkey rootCA.key -CAcreateserial -out mydomain.com.crt -days 500 -sha256
  5. Verify the certificate's content:

    cephadm@adm > openssl x509 -in mydomain.com.crt -text -noout

13.2 Host Name and Port Number Edit source

The Ceph Dashboard Web application binds to a specific TCP/IP address and TCP port. By default, the currently active Ceph Manager that hosts the dashboard binds to TCP port 8443 (or 8080 when SSL is disabled).

The dashboard Web application binds to "::" by default, which corresponds to all available IPv4 and IPv6 addresses. You can change the IP address and port number of the Web application so that they apply to all Ceph Manager instances by using the following commands:

cephadm@adm > ceph config set mgr mgr/dashboard/server_addr IP_ADDRESS
cephadm@adm > ceph config set mgr mgr/dashboard/server_port PORT_NUMBER
Tip
Tip: Configure Ceph Manager Instances Separately

Since each ceph-mgr daemon hosts its own instance of the dashboard, you may need to configure them separately. Change the IP address and port number for a specific manager instance by using the following commands (replace NAME with the ID of the ceph-mgr instance):

cephadm@adm > ceph config set mgr mgr/dashboard/NAME/server_addr IP_ADDRESS
cephadm@adm > ceph config set mgr mgr/dashboard/NAME/server_port PORT_NUMBER
Tip
Tip: List Configured Endpoints

The ceph mgr services command displays all endpoints that are currently configured. Look for the 'dashboard' key to obtain the URL for accessing the dashboard.

13.3 User Name and Password Edit source

If you do not want to use the default administrator account, create a different user account and associate it with at least one role. We provide a set of predefined system roles that you can use. For more details refer to Chapter 14, Managing Users and Roles on the Command Line.

To create a user with administrator privileges, use the following command:

cephadm@adm > ceph dashboard ac-user-create USER_NAME PASSWORD administrator

13.4 Enabling the Object Gateway Management Front-end Edit source

To use the Object Gateway management functionality of the dashboard, you need to provide the login credentials of a user with the 'system' flag enabled:

  1. If you do not have a user with the 'system' flag, create one:

    cephadm@adm > radosgw-admin user create --uid=USER_ID --display-name=DISPLAY_NAME --system

    Take note of the 'access_key' and 'secret_key' keys in the output of the command.

  2. You can also obtain the credentials of an existing user by using the radosgw-admin command:

    cephadm@adm > radosgw-admin user info --uid=USER_ID
  3. Provide the received credentials to the dashboard:

    cephadm@adm > ceph dashboard set-rgw-api-access-key ACCESS_KEY
    cephadm@adm > ceph dashboard set-rgw-api-secret-key SECRET_KEY

There are several points to consider:

  • The host name and port number of the Object Gateway are determined automatically.

  • If multiple zones are used, it will automatically determine the host within the master zonegroup and master zone. This is sufficient for most setups, but in some circumstances you may want to set the host name and port manually:

    cephadm@adm > ceph dashboard set-rgw-api-host HOST
    cephadm@adm > ceph dashboard set-rgw-api-port PORT
  • These are additional settings that you may need:

    cephadm@adm > ceph dashboard set-rgw-api-scheme SCHEME  # http or https
    cephadm@adm > ceph dashboard set-rgw-api-admin-resource ADMIN_RESOURCE
    cephadm@adm > ceph dashboard set-rgw-api-user-id USER_ID
  • If you are using a self-signed certificate (Section 13.1, “TLS/SSL Support”) in your Object Gateway setup, disable certificate verification in the dashboard to avoid refused connections caused by certificates signed by an unknown CA or not matching the host name:

    cephadm@adm > ceph dashboard set-rgw-api-ssl-verify False
  • If the Object Gateway takes too long to process requests and the dashboard runs into timeouts, the timeout value can be adjusted (default is 45 seconds):

    cephadm@adm > ceph dashboard set-rest-requests-timeout SECONDS

13.5 Enable Single Sign-On Edit source

Single Sign-On (SSO) is an access control method that enables users to log in with a single ID and password to multiple applications simultaneously.

The Ceph Dashboard supports external authentication of users via the SAML 2.0 protocol. Because authorization is still performed by the dashboard, you first need to create user accounts and associate them with the desired roles. However, the authentication process can be performed by an existing Identity Provider (IdP).

To configure Single Sign-On, use the following command:

cephadm@adm > ceph dashboard sso setup saml2 CEPH_DASHBOARD_BASE_URL \
 IDP_METADATA IDP_USERNAME_ATTRIBUTE \
 IDP_ENTITY_ID SP_X_509_CERT \
 SP_PRIVATE_KEY

Parameters:

CEPH_DASHBOARD_BASE_URL

Base URL where Ceph Dashboard is accessible (for example, 'https://cephdashboard.local').

IDP_METADATA

URL, file path, or content of the IdP metadata XML (for example, 'https://myidp/metadata').

IDP_USERNAME_ATTRIBUTE

Optional. Attribute that will be used to get the user name from the authentication response. Defaults to 'uid'.

IDP_ENTITY_ID

Optional. Use when more than one entity ID exists on the IdP metadata.

SP_X_509_CERT / SP_PRIVATE_KEY

Optional. File path or content of the certificate that will be used by Ceph Dashboard (Service Provider) for signing and encryption.

Note
Note: SAML Requests

The issuer value of SAML requests will follow this pattern:

CEPH_DASHBOARD_BASE_URL/auth/saml2/metadata

To display the current SAML 2.0 configuration, run:

cephadm@adm > ceph dashboard sso show saml2

To disable Single Sign-On, run:

cephadm@adm > ceph dashboard sso disable

To check if SSO is enabled, run:

cephadm@adm > ceph dashboard sso status

To enable SSO, run:

cephadm@adm > ceph dashboard sso enable saml2
Print this page