`mongosqld`¶

On this page

Description
Command Line Options
Configuration File
Example
Usage with Atlas

Description¶

mongosqld¶

Note

The MongoDB Connector for BI and associated utilities are compatible only with MongoDB server version 3.2 or greater.

mongosqld accepts incoming requests from a MySQL client, and proxies those requests to a mongod or mongos instance.

Command Line Options¶

Core Options¶

--help¶: Returns information on the options and use of mongosqld.

--addr¶

Default: 127.0.0.1:3307

Specifies the host address to listen on.

--version¶: Returns the mongosqld release number.

--config <path>¶: Specifies the path to a configuration file.

--schema <filename>¶: Specifies the path to a schema file or the schema directory.

--schemaDirectory <directoryname>¶: Deprecated since version 2.2.

Use --schema instead.

--mongo-uri <uri>¶

Default: mongodb://localhost:27017

Specifies a MongoDB connection string to connect to.

The --mongo-uri option only supports the following options within the connection string:

For more information on these URI options see Read Preference Options and Replica Set Option.

For options set in the Mongo URI not included in the list above, use the equivalent mongosqld option. For the complete list of mongosqld options, see Command Line Options.

Example

Instead of specifying a username and password in your connection string, run mongosqld with the --auth option to direct mongosqld to pass the authentication credentials provided by the MySQL client to the MongoDB server.

Similarly, instead of enabling ssl in the connection string, run mongosqld with --mongo-ssl.

URI options not in the list above nor in the list of supported mongosqld options are not supported.

--mongo-versionCompatibility <version-number>¶: Specifies that mongosqld must only use features supported by the specified version of MongoDB. Only necessary when used with replica sets in which members use different MongoDB versions. The minimum allowable MongoDB version is 3.2.

--maxVarcharLength <length>¶: New in version 2.2.

Specifies the maximum length, in characters, for all varchar fields. If mongosqld encounters a string that is longer than the maximum length, mongosqld truncates it to the maximum length and logs a warning.

Log Options¶

--logAppend¶: Append new logging output to an existing log file specified by --logPath.

--logPath <filename>¶

Default: stderr

Specifies a path to a log file for storing logging output.

--verbose, -v¶: Specifies that mongosqld should provide more detailed log output. Include multiple times for more verbosity (e.g. -vvvvv).

--quiet¶: Hides all log output.

MongoDB TLS/SSL Options¶

--mongo-ssl¶

Default: False

Instructs mongosqld to use TLS/SSL when connecting to a MongoDB instance.

--mongo-sslPEMKeyFile <filename>¶

Specifies the .pem file containing both the TLS/SSL certificate and key for the MongoDB instance. Specify the file name of the .pem file using relative or absolute paths.

This option is required when using the --mongo-ssl option to connect to a mongod or mongos that has CAFile enabled without net.ssl.allowConnectionsWithoutCertificates.

--mongo-sslPEMKeyPassword <password>¶: Specifies the path to a file containing the certificate and private key for connecting to MongoDB.

--mongo-sslAllowInvalidHostnames¶: Permits mongosqld to connect to a MongoDB server whose hostname differs from the hostname on its TLS/SSL certificate.

--mongo-sslAllowInvalidCertificates¶: Permits the MongoDB instance to present an invalid server SSL/TLS certificate. When using the allowInvalidCertificates setting, MongoDB logs the use of the invalid certificate as a warning.

--mongo-sslCAFile <filename>¶: Specifies the MongoDB instance’s .pem file containing the root certificate chain from the Certificate Authority. Specify the file name of the .pem file using relative or absolute paths.

Warning

For SSL connections (--mongo-ssl) to mongod and mongos, if the mongosqld runs without the --mongo-sslCAFile, mongosqld will not attempt to validate the server certificates. This creates a vulnerability to expired mongod and mongos certificates as well as to foreign processes posing as valid mongod or mongos instances. Ensure that you always specify the CA file to validate the server certificates in cases where intrusion is a possibility.

--mongo-sslCRLFile <filename>¶: Specifies the MongoDB instance’s .pem file containing the certificate revocation list.

--mongo-sslFIPSMode¶: Enable FIPS mode in the installed OpenSSL library.

Client TLS/SSL Options¶

--sslPEMKeyFile <filename>¶: Specifies the .pem file containing both the TLS/SSL certificate and key for MySQL clients. Specify the file name of the .pem file using relative or absolute paths.

--sslPEMKeyPassword <password>¶: Specifies the password used to decrypt the private key specified by --sslPEMKeyFile.

--sslAllowInvalidCertificates¶: Permits MySQL clients to present invalid client TLS/SSL certificates.

--sslAllowInvalidHostnames¶: Permits mongosqld to connect to a MySQL server whose hostname differs from the hostname on its TLS/SSL certificate.

--sslCAFile <filename>¶: Specifies the MySQL client’s .pem file containing the root certificate chain from the Certificate Authority. Specify the file name of the .pem file using relative or absolute paths.

--sslCRLFile <filename>¶: Specifies the MySQL client’s .pem file containing the certificate revocation list.

--auth¶: Require authentication for incoming client requests.

--defaultAuthSource <authSource>¶

Default: admin

Specifies the default MongoDB authentication source. Set this value to specify a default source that mongosqld uses when authenticating with a MongoDB database. The authentication mechanisms GSSAPI and PLAIN use the $external source, while SCRAM-SHA-1 uses a MongoDB database as its source.

If no value is given for this option it defaults to the the MongoDB admin database.

The $external authentication source stores a reference to system users in a MongoDB database called $external, but the credentials are stored in an external, non-MongoDB system, such as an LDAP server.

Any connection which uses the default value can omit the source parameter from its MySQL or Tableau username.

--defaultAuthMechanism <authMechanism>¶

Default: SCRAM-SHA-1

Specifies the default authentication mechanism. Set this value to specify a default mechanism for connecting to mongosqld. Any connection which uses this specified default value can omit the mechanism value from its MySQL or Tableau username.

Service Options¶

--serviceName <service-name>¶: Name of the system service which runs mongosqld.

--serviceDisplayName <service-name>¶: Display name of the system service which runs mongosqld.

--serviceDescription <service-name>¶: Description of the system service which runs mongosqld.

Socket Options¶

--filePermissions <mode>¶

Default: 448

Specify the permissions for the Unix domain socket file.

--noUnixSocket¶: Disable listening on Unix domain sockets.

--unixSocketPrefix <path>¶

Default: /tmp

Specify an alternative directory for the mongosqld Unix domain socket.

mongosqld will create a socket file called mysql.sock underneath this path. If you do not specify --unixSocketPrefix, the socket will exist at /tmp/mysql.sock.

Configuration File¶

You may configure mongosqld using a YAML configuration file. This file may contain the settings listed in the following sections.

Logging Options¶

systemLog:
  logAppend: <boolean>
  path: <string>
  quiet: <boolean>
  verbosity: <integer>

Name	Type	Corresponds to
`systemLog.logAppend`¶	boolean	`--logAppend`
`systemLog.path`¶	string	`--logPath`
`systemLog.quiet`¶	boolean	`--quiet`
`systemLog.verbosity`¶	integer	`--verbose`

Schema Options¶

schema:
  path: <string>
  maxVarcharLength: <integer>

Name	Type	Corresponds to
`schema.path`¶	string	`--schema`
`schema.maxVarcharLength`¶	integer	`--maxVarcharLength`

Runtime Options¶

runtime:
  memory:
    maxPerStage: <integer>

runtime.memory.maxPerStage¶

Type: integer

Default: unlimited

Specifies the maximum amount of memory in bytes that a query execution stage may use.

Network Options¶

net:
  bindIp: <string>
  port: <integer>
  unixDomainSocket:
    enabled: <boolean>
    pathPrefix: <string>
    filePermissions: <string>
  ssl:
    allowInvalidCertificates: <boolean>
    PEMKeyFile: <string>
    PEMKeyPassword: <string>
    CAFile: <string>

Name	Type	Corresponds to
`net.bindIp`¶	string	The hostname component of `--addr` Changed in version 2.2: To bind to multiple IP addresses, enter a list of comma separated values. Example “72.198.41.200,72.198.41.201,72.198.41.202”
`net.port`¶	integer	The port component of `--addr`
`net.unixDomainSocket.enabled`¶	boolean	Inverse of `--noUnixSocket`
`net.unixDomainSocket.pathPrefix`¶	string	`--unixSocketPrefix`
`net.unixDomainSocket.filePermissions`¶	string	`--filePermissions`
`net.ssl.allowInvalidCertificates`¶	boolean	`--sslAllowInvalidCertificates`
`net.ssl.PEMKeyFile`¶	string	`--sslPEMKeyFile`
`net.ssl.PEMKeyPassword`¶	string	`--sslPEMKeyPassword`
`net.ssl.CAFile`¶	string	`--sslCAFile`

Security Options¶

security:
  enabled: <boolean>
  defaultMechanism: <string>
  defaultSource: <string>

Name	Type	Corresponds to
`security.enabled`¶	boolean	`--auth`
`security.defaultMechanism`¶	string	`--defaultAuthMechanism`
`security.defaultSource`¶	string	`--defaultAuthSource`

MongoDB Host Options¶

mongodb:
  versionCompatibility: <string>
  net:
    uri: <string>
    ssl:
      enabled: <boolean>
      allowInvalidCertificates: <boolean>
      allowInvalidHostnames: <boolean>
      PEMKeyFile: <string>
      PEMKeyPassword: <string>
      CAFile: <string>
      CRLFile: <string>
      FIPSMode: <boolean>

Name	Type	Corresponds to
`mongodb.versionCompatibility`¶	string	`--mongo-versionCompatibility`
`mongodb.net.uri`¶	string	`--mongo-uri`
`mongodb.net.ssl.enabled`¶	boolean	`--mongo-ssl`
`mongodb.net.ssl.allowInvalidCertificates`¶	boolean	`--mongo-sslAllowInvalidCertificates`
`mongodb.net.ssl.allowInvalidHostnames`¶	boolean	`--mongo-sslAllowInvalidHostnames`
`mongodb.net.ssl.PEMKeyFile`¶	string	`--mongo-sslPEMKeyFile`
`mongodb.net.ssl.PEMKeyPassword`¶	string	`--mongo-sslPEMKeyPassword`
`mongodb.net.ssl.CAFile`¶	string	`--mongo-sslCAFile`
`mongodb.net.ssl.CRLFile`¶	string	`--mongo-sslCRLFile`
`mongodb.net.ssl.FIPSMode`¶	boolean	`--mongo-sslFIPSMode`

Process Management Options¶

processManagement:
  service:
    name: <string>
    displayName: <string>
    description: <string>

Name	Type	Corresponds to
`processManagement.service.name`¶	string	`--serviceName`
`processManagement.service.displayName`¶	string	`--serviceDisplayName`
`processManagement.service.description`¶	string	`--serviceDescription`

Example¶

If you wish to specify a configuration file which saves logs to /var/log/mongosqld.log and loads a schema from /var/schema.drdl, you may save a file such as the following to /etc/mongosqld.conf:

Warning

All paths specified in the configuration file must be absolute, e.g. they must begin with /.

copy

systemLog:
  path: /var/log/mongosqld.log
schema:
  path: /var/schema.drdl

You may then start mongosqld with the --config option:

copy

mongosqld --config /etc/mongosqld.conf

For more information on starting mongosqld as a system service, see the Installation Guide for your operating system.

Usage with Atlas¶

Atlas is a cloud service for running, monitoring, and maintaining MongoDB deployments, including the provisioning of dedicated servers for the MongoDB instances.

Atlas uses TLS/SSL to encrypt connections and enforces authentication by default.

Note

With the MongoDB Atlas free tier, BI Connector cannot run aggregation pipelines using the allowDiskUse option. This option allows aggregation stages to write data as temporary files to disk. To review the MongoDB Atlas free tier constraints, see the MongoDB Atlas manual.

To connect the MongoDB Connector for BI to an Atlas cluster, you must provide mongosqld with a .pem key file.

mongosqld can use any valid TLS certificate issued by a certificate authority, or a self-signed certificate. If you use a self-signed certificate, although the communications channel will be encrypted, there will be no validation of server identity. Although such a situation will prevent eavesdropping on the connection, it leaves you vulnerable to a man-in-the-middle attack. Using a certificate signed by a trusted certificate authority will permit your MySQL client to verify the server’s identity.

For testing purposes, you can create a .pem key file named test.pem using the openssl tool:

copy

openssl req -nodes -newkey rsa:2048 -keyout test.key -out test.crt -x509 -days 365 -subj "/C=US/ST=test/L=test/O=test Security/OU=IT Department/CN=test.com"
cat test.crt test.key > test.pem

Start mongosqld with the --auth and --sslPEMKeyFile options.

If you named your key file test.pem as in the previous example, you can run the following, substituting your schema file and cluster URI:

Note

Do not specify a username and password in --mongo-uri. The connection string should only contain the list of servers.

copy

mongosqld --mongo-ssl --auth --sslPEMKeyFile test.pem --schema <schema.drdl> --mongo-uri <uri>

Pass your username, password, and authentication database to your SQL client. For example, using mysql without verifying your mongosqld server certificate:

copy

mysql --host <mongosqld-host> --port <mongosqld-port> -u <username>?source=admin -p --ssl-mode required --enable-cleartext-plugin

Refer to Connect from the MySQL Client for more details on using the mysql client with the BI Connector.

← mongodrdl C Authentication Plugin →

mongosqld¶

Description¶

Command Line Options¶

Core Options¶

Log Options¶

MongoDB TLS/SSL Options¶

Client TLS/SSL Options¶

Service Options¶

Socket Options¶

Configuration File¶

Logging Options¶

Schema Options¶

Runtime Options¶

Network Options¶

Security Options¶

MongoDB Host Options¶

Process Management Options¶

Example¶

Usage with Atlas¶

`mongosqld`¶