MySQL AI User Guide

2.3 Command-line Installation

The MySQL AI Installer can also be run in command-line mode, without invoking the installation GUI. Execute the following command in the folder where you have extracted the RPMs from the MySQL AI RPM bundle: 

$> sudo mysql-ai-setup --cli [options]
options:
        --option-long-name[=value-list]
    |   -option-short-name [value-list]

value-list:
    value[,value[,...]]

The command options are described in groups below (use the -h or --help option to see the option descriptions):

Installation Type

  • --skip-install: Do not install anything. This is useful for testing system requirements and installation options.

Install Without Satisfying Minimum Requirements

  • --skip-requirements: Install even if the system does not satisfy the minimum requirements.

    Warning

    MySQL AI might not work or might have performance issues if installed on a system that does not satisfy the minimum requirements.

User and Password

  • --mysql-root-user=username: User name and password for the MySQL root user.

  • --mysql-root-password=password: Password for the MySQL root user. The password must satisfy the MEDIUM level policy of the validate_password component.

  • --mysql-root-allow-remote-connection: The root user is allowed to connect from hosts other than localhost. See the Warning near the beginning of Chapter 2, Installing MySQL AI.

MySQL Studio, MySQL Shell Workbench and MySQL Router (MySQL REST Service)

Note

Check the Warning near the beginning of Chapter 2, Installing MySQL AI before installing the MySQL Shell GUI and MySQL Router (MySQL REST Service).

  • --install-mysql-studio: Install the MySQL Studio service.

  • --mysql-studio-port=port#: Replace the default port number (8000) with another one for MySQL Studio's server to listen for connections. A warning is displayed if the port you entered is already in use or will be used by another MySQL AI component.

  • --skip-mysql-studio: Skip installing MySQL Studio.

  • --install-mysql-shell-gui: Install the MySQL Shell Workbench service.

  • --skip-mysql-shell-gui: Skip installing MySQL Shell Workbench.

  • --mysql-shell-gui-port=port#: Replace the default port number (8000) with another one for MySQL Shell GUI web server to listen for connections. A warning is displayed if the port you entered is already in use or will be used by another MySQL AI component.

  • --skip-mysql-router: Skip installing MySQL Router and MySQL REST Service.

  • --mysql-router-port=port#: Replace the default HTTPS port number (8443) with another one for the MySQL REST Service web server to listen to connections. A warning is displayed if the port you entered is already in use or will be used by another MySQL AI component.

  • --mysql-router-jwt-secret=jwt-secret: Provide a secret for JSON Web Secret (JWS) tokens. If this option is not specified, a random secret will be created by default.

Vector Store

  • --secure-file-priv=filepath: Specify the directory for loading documents into the vector store. The location must be configured by the server system variable secure_file_priv for mysqld to import data securely from it. If the option is not specified, the default location is /var/lib/mysql-files. If you specify a directory that does not exist, it will be created.

Certificates

Configure TLS certificates for encrypted communication with each of the following components of MySQL AI.

Notes

  • The certificate, key, and bundle files specified must be readable by root user who installs MySQL AI; adjust their file permissions if needed.

  • The certificate, key, and bundle files must not be passphrase protected.

  • A file path to a certificate bundle file is expected in the *-certificate option. However, the path can also point to either a certificate file or a bundle file that does not contain the private key, in which case use the *-private-key to provide the file path for the private key or, for the PEM format only, the actual key string.

MySQL AI uses certificates keystore in p12 for encryption purposes. Two entities are required for creating certificates:

  • AI_PLUGIN (CN = ai_plugin)

  • AI_ENGINE (CN = ai_engine)

To create certificates, you first need to create a config file with the details of the Root CA (Certificate Authority). See the example below: 

[ req ]
distinguished_name=req_distinguished_name
x509_extensions=v3_ca
prompt = no

[ req_distinguished_name ]
C=US
L=San Francisco
CN=MyRootCA

[ v3_ca ]
basicConstraints=CA:TRUE
keyUsage=keyCertSign,cRLSign
subjectAltName=@alt_names

[ alt_names ]
DNS.1=MyRootCA_Alt

The CN value, MyRootCA, identifies the RootCA itself. You can customize this value to your specification.

After creating the config file, you can generate the Root CA certificate with the following command: 

openssl req -x509 -config ca.conf -sha256 -nodes -days 3650 -newkey rsa:2048 -keyout ca_private_key.pem -out cert_chain.pem

The value 3650 specifies the expiry duration for the certificate (about 10 years). You can change this value to your specification.

After running this command, two new files are generated: ca_private_key.pem (private key) and cert_chain.pem (public key certificate chain signed by self).

After generating the Root CA certificates, you can run the script to generate a certificate for an entity signed by the previous Root CA. See the following example: 

#!/bin/sh


generate_cert() {
    local CN="$1"

    if [[ "$CN" == "" ]]; then
      CN=$(hostname)
    fi

    # Determine subject for the client certificate
    local SUBJECT="/C=US/O=Oracle/UID=${CN}/CN=${CN}"

    # 1. Create a new private key and corresponding CSR for the client
    openssl req -newkey rsa:2048 -sha256 -nodes \
        -keyout "private_key.pem" \
        -out "client_cert.csr" \
        -subj "$SUBJECT"

    # 2. Create SAN configuration file
    local SAN_CONFIG_FILE="$(mktemp)"
    echo "
keyUsage=digitalSignature,keyEncipherment
" > "$SAN_CONFIG_FILE"

    # 3. Sign the client CSR using the MyRootCA, creating a client certificate
    openssl x509 -req \
        -CA "cert_chain.pem" \
        -CAkey "ca_private_key.pem" \
        -in "client_cert.csr" \
        -out "certificate.pem" \
        -days 365 \
        -CAcreateserial \
        -extfile "$SAN_CONFIG_FILE"
    rm "$SAN_CONFIG_FILE"

    # 4. Package the client key and certificate into a PKCS12 file
    openssl pkcs12 -export \
        -out "${CN}_keystore.p12" \
        -inkey "private_key.pem" \
        -in "certificate.pem" \
        -certfile "cert_chain.pem" \
        -name "keystore" \
        -password pass:

    # Cleanup
    rm client_cert.csr certificate.pem private_key.pem cert_chain.srl

    chmod 644 "${CN}_keystore.p12"
}

generate_cert "$@"

In the example, -days 365 refers to the expiry duration of the certificate. You can customize this value to your specification. You must run the script in the same directory where the Root CA certificates were generated.

After generating the certificate, you can run the following script to generate the certificate for the AI Plugin (CN = ai_plugin): 

bash create_certs.sh ai_engine

This generates the .p12 file ai_plugin_keystore.p12.

Generating the Root CA certificate is a one-time activity. To renew certificates, you must save and use the the Root CA certificates using the previous steps. If you place renewed certificates in the appropriate location, they are automatically loaded before the expiration date.

Certificates for MySQL Server.  Provide the certificate and private key in PEM or PKSC#12 format for communication with MySQL Server using the mysql and mysqlx protocols. If no certificate is supplied, a self-signed certificate is generated.

  • --mysql-server-tls-certificate=filepath: Location of the certificate bundle used for HTTPS communication by MySQL Server.

  • --mysql-server-tls-private-key=filepath: The private key used for HTTPS communication by MySQL Server. This option is needed only if --mysql-server-tls-certificate points to a certificate file, or a bundle file that does not contain the private key. Provide with this option the file path for the private key or, for PEM format only, the actual key string.

Certificates for AI Plugin and Machine Learning Services.  Provide the certificates in PEM or PKSC#12 format. Two distinct certificate bundles are required for the two components. If no certificates and keys are provided for any of the two components, encrypted communication with the component is disabled, unless self-signed certificates, with specified common names, are requested.

  • --skip-ai-encryption: Use this option to explicitly turn off encryption for communication with the AI plugin and Machine Learning services. If this command line option is absent, installer will quit without installing MySQL AI unless certificates are provided or self-signed certificates are requested (see options below).

  • --ai-plugin-certificate=filepath: Location of the certificate bundle used for HTTPS communication with the AI plugin.

  • --ai-plugin-private-key=filepath: The private key used for HTTPS communication with the AI plugin. This option is needed only if --ai-plugin-certificate points to a certificate file, or a bundle file that does not contain the private key. Provide with this option the file path for the private key or, for PEM format only, the actual key string.

  • --ai-plugin-common-name=string: Common name for the certificate for communication with the AI plugin. This option is only needed if you want to correct the installer's reading of the common name from your certificate.

  • --ai-plugin-create-self-signed-certificate=Common_Name: Create a self-signed certificate for communication with the AI plugin with the common name specified by this option.

  • --ai-services-certificate=filepath: Location of the certificate bundle used for HTTPS communication with the Machine Learning Service.

  • --ai-services-private-key=filepath. The private key used for HTTPS communication with the AI plugin. This option is needed only if --ai-services-certificate points to a certificate file, or a bundle file that does not contain the private key. Provide with this option the file path for the private key or, for the PEM format only, the actual key string.

  • --ai-services-common-name=string: Common name for the certificate for communication with the Machine Learning service. This option is only needed if you want to correct the installer's reading of the common name from your certificate.

  • --ai-services-create-self-signed-certificate=Common_Name: Create a self-signed certificate for communication with the Machine Learning service with the common name specified by this option.

Certificates for MySQL Studio, MySQL Shell Workbench, and MySQL Router (MySQL REST Service):  Provide the certificate and private key in PEM or PKSC#12 format. If either of the certificates is not supplied, a self-signed certificate will be created for the respective service.

  • --mysql-studio-https-certificate=filepath: Location of the certificate bundle used for HTTPS communication by the MySQL Studio.

  • --mysql-studio-https-private-key=filepath: The private key used for HTTPS communication by MySQL Studio. This option is needed only if --mysql-studio-https-certificate points to a certificate file, or a bundle file that does not contain the private key. Provide with this option the file path for the private key or, for the PEM format only, the actual key string.

  • --mysql-shell-https-certificate=filepath: Location of the certificate bundle used for HTTPS communication by the MySQL Shell Workbench service.

  • --mysql-shell-https-private-key=filepath: The private key used for HTTPS communication by the MySQL Shell Workbench service. This option is needed only if --mysql-shell-https-certificate points to a certificate file, or a bundle file that does not contain the private key. Provide with this option the file path for the private key or, for the PEM format only, the actual key string.

  • --mysql-router-https-certificate=filepath: Location of the certificate bundle used for HTTPS communication by MySQL Router (MySQL REST Service).

  • --mysql-router-https-private-key=filepath: The private key used for HTTPS communication by MySQL Router (MySQL REST Service). This option is needed only if --mysql-router-https-certificate points to a certificate file, or a bundle file that does not contain the private key. Provide with this option the file path for the private key or, for the PEM format only, the actual key string.

Certificate Revocation Lists.  Optionally, add a Certificate Revocation List (CRL) to enable clients to check whether a certificate has been revoked before its expiration date. This helps ensure that compromised or invalid certificates are not trusted, even if they have not yet expired, allowing for improved certificate management and timely response to security issues.

  • You must provide the CRL, which contains the serial numbers of revoked certificates, to both the AI plugin and the MySQL server. If you need to replace revoked certificates with new certificates, the new certificates should have the same names and be placed in the same location as the originals. If revoked certificates are not properly replaced, connections may fail or the AI Services may shut down.

  • --sslCrl=filepath: The path to the CRL file when configuring MySQL server (AI Engine). For AI plugin, configure the file in the rapid_ssl_crl global variable. To configure the variable, the state of rapid_bootstrap must be IDLE or OFF.

  • If you create a new CRL or update a CRL, the latest CRL file is reloaded, and all existing TLS connections are refreshed by closing the current SSL context and recreating it.

  • If the CRL is invalid, (for example it is signed by a different Root CA, it is corrupted or empty, or it is expired), no connection can occur, and any existing connections will break.

  • The CRL file must be encrypted without a passphrase. The file and file path must be no more than 256 bytes.

  • You can use the following template to create a CRL. 

    #!/bin/sh

# Copyright (c) 2025, Oracle and/or its affiliates.

generate_crl() {
  local OUTPUT_DIR="$1"
  local KEYSTORE_TO_BE_REVOKED="$2"
  if [[ ! -e ${OUTPUT_DIR}/index.txt ]]; then
    touch ${OUTPUT_DIR}/index.txt
  fi
  echo "
[ ca ]
default_ca = "MyRootCA"

[ MyRootCA ]
dir = ${OUTPUT_DIR}
certs = ${OUTPUT_DIR}
crl_dir = ${OUTPUT_DIR}
new_certs_dir = ${OUTPUT_DIR}
database = ${OUTPUT_DIR}/index.txt

private_key = ${OUTPUT_DIR}/ca_private_key.pem
certificate = ${OUTPUT_DIR}/cert_chain.pem

default_crl_days = 30

default_md        = sha256
" > "$OUTPUT_DIR/ca.cnf"
  #  Extract the certificate from the revoked keystore file
  openssl pkcs12 -in "$KEYSTORE_TO_BE_REVOKED" -out "$OUTPUT_DIR/certificate.pem" -clcerts -nokeys -passout pass: -passin pass:
  openssl ca -config "$OUTPUT_DIR/ca.cnf" -revoke "$OUTPUT_DIR/certificate.pem"
  openssl ca -gencrl -out "$OUTPUT_DIR/crl.pem" -config "$OUTPUT_DIR/ca.cnf"
  rm "$OUTPUT_DIR/ca.cnf" "$OUTPUT_DIR/certificate.pem"
}
generate_crl "$@"
MySQL Documentation Library