3.1 mcmd, the MySQL Cluster Manager Agent

mcmd is the MySQL Cluster Manager agent program; invoking this executable starts the MySQL Cluster Manager Agent, to which you can connect using the mcm client (see Section 3.3, “Starting the MySQL Cluster Manager Client”, and Chapter 4, MySQL Cluster Manager Client Commands, for more information).

You can modify the behavior of the agent in a number of different ways by specifying one or more of the options discussed in this sections. Most of these options can be specified either on the command line or in the agent configuration file (normally etc/mcmd.ini). (Some exceptions include the --defaults-file and --bootstrap options, which, if used, must be specified on the command line, and which are mutually exclusive with one another.) For example, you can set the agent's cluster logging level to warning instead than the default message in either one of the following two ways:

• Include --log-level=warning on the command line when invoking mcmd.

  Note

  When specifying an agent configuration option on the command line, the name of the option is prefixed with two leading dash characters (--).

• Include the following line in the agent configuration file:

  log-level=warning

  Note

  You can change the logging level at runtime using the mcm client change log-level command.

  When used in the configuration file, the name of the option should not be prefixed with any other characters. Each option must be specified on a separate line. You can comment out all of a given line by inserting a leading hash character (#), like this:

  #log-level=warning

  You can also comment out part of a line in this way; any text following the # character is ignored, to the end of the current line.

The following table contains a summary of agent options that are read on startup by mcmd. More detailed information about each of these options, such as allowed range of values, can be found in the list following the table.

Table 3.1 MySQL Cluster Manager Agent (mcmd) Option Summary

Option Name	Description	Introduced
--agent-uuid	Set the agent's UUID; needed only when running multiple agent processes on the same host
--basedir	Directory to use as prefix for relative paths in the configuration
--bootstrap	Bootstrap a default cluster on startup
--copy-port	Specify the port for file copy operations	1.4.2
--daemon	Run in daemon mode. The option applies only to Linux and other Unix-like platforms
--defaults-file	Configuration file to use
--event-threads	Number of event handler threads to use
--help	Show application options
--help-all	Show all options (application options and manager module options)
--help-manager	Show manager module options
--initial	Wipes the contents in the agent's configuration store after making a backup	1.4.7
--keepalive	Try to restart mcmd in the event of a crash. The option applies only to Linux and other Unix-like platforms
--log-backtrace-on-crash	Attempt to load debugger in case of a crash
--log-file	Name of the file to write the log to
--log-level	Set the mcmd logging level
--log-use-syslog	Log to syslog
--manager-directory	Directory used for manager data storage
--manager-password	Password for the mcmd user-account
--manager-port	Port for client to use when connecting to manager
--manager-username	Username for the mcmd user-account
--max-open-files	Maximum number of open files (ulimit -n)
--pid-file	Specify PID file (used if running as daemon)
--plugin-dir	Directory in which to look for plugins
--plugins	Comma-separated list of plugins to load; must include "manager"
--verbose-shutdown	Always log the exit code when shutting down
--version	Show the manager version
--xcom-port	Specify the XCOM port

MySQL Cluster Manager Agent (mcmd) Option Descriptions

The following list contains descriptions of each startup option available for use with mcmd, including allowed and default values. Options with their Type unmentioned need only be specified in order to take effect; you should not try to set a value for them.

• --agent-uuid=uuid

  Command-Line Format	--agent-uuid=uuid
  Type	String
  Default Value	[set internally]

  Set a UUID for this agent. Normally this value is set automatically, and needs to be specified only when running more than one mcmd process on the same host.

• --basedir=dir_name

  Command-Line Format	--basedir=dir_name
  Type	Directory name
  Default Value	.

  Directory with path to use as prefix for relative paths in the configuration.

• --bootstrap

  Command-Line Format	--bootstrap

  Start the agent with default configuration values, create a default one-machine cluster named mycluster, and start it. This option works only if no clusters have yet been created.

• --copy-port

  Command-Line Format	--copy-port=#
  Introduced	1.4.2
  Type	Numeric
  Default Value	0
  Minimum Value	0
  Maximum Value	65535

  Allows you to specify the port for file copy operations. The default is 0.

• --daemon

  Command-Line Format	--daemon
  Platform Specific	Linux

  Run mcmd as a daemon.

• --defaults-file=filename

  Command-Line Format	--defaults-file=file_name
  Type	File name
  Default Value	etc/mcmd.ini

  Set the file from which to read configuration options. The default is etc/mcmd.ini. See Section 2.4, “MySQL Cluster Manager Configuration File”, for more information.

• --event-threads=#

  Command-Line Format	--event-threads=#
  Type	Numeric
  Default Value	1
  Minimum Value	1
  Maximum Value	[system dependent]

  Number of event handler threads to use. The default is 1, which is sufficient for most normal operations.

• --help, -?

  Command-Line Format	--help

  mcmd help output is divided into Application and Manager sections. When used with mcmd, --help causes the Application options to be shown, as shown here:

  $> mcmd --help
  Usage:
    mcmd [OPTION...] - MySQL Cluster Manager
  
  Help Options:
    -?, --help                          Show help options
    --help-all                          Show all help options
    --help-manager                      Show options for the manager-module
  
  Application Options:
    -V, --version                       Show version
    --defaults-file=<file>              configuration file
    --verbose-shutdown                  Always log the exit code when shutting down
    --daemon                            Start in daemon-mode
    --basedir=<absolute path>           Base directory to prepend to relative paths in the config
    --pid-file=<file>                   PID file in case we are started as daemon
    --plugin-dir=<path>                 Path to the plugins
    --plugins=<name>                    Plugins to load
    --log-level=<string>                Log all messages of level ... or higher
    --log-file=<file>                   Log all messages in a file
    --log-use-syslog                    Log all messages to syslog
    --log-backtrace-on-crash            Try to invoke debugger on crash
    --keepalive                         Try to restart mcmd if it crashed
    --max-open-files                    Maximum number of open files (ulimit -n)
    --event-threads                     Number of event-handling threads (default: 1)

• --help-all

  Command-Line Format	--help-all

  mcmd help output is divided into Application and Manager sections. When used with --help-all, mcmd displays both the Application and the Manager options, like this:

  $> mcmd --help-all
  Usage:
    mcmd [OPTION...] - MySQL Cluster Manager
  
  Help Options:
    -h, --help                          Show help options
    --help-all                          Show all help options
    --help-manager                      Show options for the manager-module
  
  manager-module
    --bootstrap                         Bootstrap a cluster on localhost on initial startup
    --copy-port=<copy_port>             Port for file copy operations (default: 0)
    --initial                           Wipes the repository files after making a backup
    --manager-directory=<directory>     Path to mcmd config information
    --manager-password=<password>       Password for the mcmd user-account (default: super)
    --manager-port=<client_port>        Port to contact the mcmd (default: 1862)
    --manager-username=<username>       Username for the mcmd user-account (default: mcmd)
    --xcom-port=<xcom_port>             Xcom port for mcmds to communicate (default: 18620)
  
  Application Options:
    -V, --version                       Show version
    --defaults-file=<file>              configuration file
    --verbose-shutdown                  Always log the exit code when shutting down
    --daemon                            Start in daemon-mode
    --basedir=<absolute path>           Base directory to prepend to relative paths in the config
    --pid-file=<file>                   PID file in case we are started as daemon
    --plugin-dir=<path>                 Path to the plugins
    --plugins=<name>                    Plugins to load
    --log-level=<string>                Log all messages of level ... or higher
    --log-file=<file>                   Log all messages in a file
    --log-use-syslog                    Log all messages to syslog
    --log-backtrace-on-crash            Try to invoke debugger on crash
    --keepalive                         Try to restart mcmd if it crashed
    --max-open-files                    Maximum number of open files (ulimit -n)
    --event-threads                     Number of event-handling threads (default: 1)

• --help-manager

  Command-Line Format	--help-manager

  mcmd help output is divided into Application and Manager sections. When used with --help-manager, mcmd displays the Manager options, like this:

  $> mcmd --help-manager
  Usage:
    mcmd [OPTION...] - MySQL Cluster Manager
  
  manager-module
    --bootstrap                         Bootstrap a cluster on localhost on initial startup
    --copy-port=<copy_port>             Port for file copy operations (default: 0)
    --initial                           Wipes the repository files after making a backup
    --manager-directory=<directory>     Path to mcmd config information
    --manager-password=<password>       Password for the mcmd user-account (default: super)
    --manager-port=<client_port>        Port to contact the mcmd (default: 1862)
    --manager-username=<username>       Username for the mcmd user-account (default: mcmd)
    --xcom-port=<xcom_port>             Xcom port for mcmds to communicate (default: 18620)

• --initial

  Command-Line Format	--initial
  Introduced	1.4.7

  For MySQL Cluster Manager 1.4.7 and later: Make a backup of the agent's configuration store (mcm_data/rep/) like the backup agents command would do for the local host, and then wipe the configuration store's contents before starting mcmd. The agent's configuration is then recovered from other agents. This is useful when an agent has fallen into an inconsistent state and cannot be properly restarted.

• --keepalive

  Command-Line Format	--keepalive
  Platform Specific	Linux

  Use this option to cause mcmd to attempt to restart in the event of a crash.

• --log-backtrace-on-crash

  Command-Line Format	--log-backtrace-on-crash

  Attempt to load the debugger in the event of a crash. Not normally used in production.

• --log-file=filename

  Command-Line Format	--log-file=file
  Type	File name
  Default Value	mcmd.log

  Set the name of the file to write the log to. The default is mcmd.log in the installation directory. On Linux and other Unix-like platforms, you can use a relative path; this is in relation to the MySQL Cluster Manager installation directory, and not to the bin or etc subdirectory. On Windows, you must use an absolute path, and it cannot contain any spaces; in addition, you must replace any backslash (\) characters in the path with forward slashes (/).

• --log-level=level

  Command-Line Format	--log-level=level
  Type	Enumeration
  Default Value	message
  Valid Values	critical error warning message info debug

  Sets the mcmd log severity level. Possible values for this option and their descriptions are listed in Table 3.2, “MySQL Cluster Manager Agent Log Levels” in descending level of severity. When the option is set to a certain severity level, all events of that or higher levels are logged. message is the default log level, and is the recommended setting for a production environment; running on a more severe log level produces fewer messages and makes it harder to trace a problem when it occurs.

  Table 3.2 MySQL Cluster Manager Agent Log Levels

  Level of Severity	Description
  critical	Conditions that should be corrected immediately, such as a corrupted MySQL Cluster Manager data repository
  error	Conditions that should be corrected, such as configuration errors
  warning	Conditions that do not fail executions, but may require user attention
  message	Messages on main events of the site and from command execution
  info	Informational messages to provide users with some execution details
  debug	Debugging messages that give execution details useful for developers. This causes large log files if used over a long period of time.

  
  

  You can also change the mcmd logging level at runtime using the change log-level command with the mcm client. While the setting of the --log-level option is applied only to the host whose mcmd agent uses the option (either at the command line or in a configuration file), the change log-level client command can be used to apply the logging level to an entire management site or to specific hosts.

• --log-use-syslog

  Command-Line Format	--log-use-syslog

  Write logging output to syslog.

• --manager-directory=dir_name

  Command-Line Format	--manager-directory=dir
  Type	Directory name
  Default Value	../mcm_data (relative to the installation directory of MySQL Cluster Manager)

  Set the location of the agent repository, which contains collections of MySQL Cluster Manager data files and MySQL NDB Cluster configuration and data files. The value must be a valid absolute path. On Linux, if the directory does not exist, it is created; on Windows, the directory must be created if it does not exist. additionally on Windows, the path may not contain any spaces or backslash (\) characters; backslashes must be replaced with forward slashes (/).

  The default location is ../mcm_data (relative to the installation directory of MySQL Cluster Manager). If you change the default, you should use a standard location external to the MySQL Cluster Manager installation directory, such as /var/opt/mcm on Linux.

  In addition to the data files for all the clusters under the control of MySQL Cluster Manager, the manager-directory also contains a rep directory in which mcmd configuration and metadata are kept. Normally, there is no need to interact with these directories beyond specifying the location of the manager-directory in the agent configuration file (mcmd.ini); see exceptions in, for example, Section 3.8, “Restoring a MySQL Cluster Manager Agent with Data from Other Agents” and Section 3.7, “Backing Up and Restoring MySQL Cluster Manager Agents”.

• --manager-port=#

  Command-Line Format	--manager-port=port
  Type	Numeric
  Default Value	1862

  Specify the port used by MySQL Cluster Manager client connections. Any valid TC/IP port number can be used. Normally, there is no need to change it from the default value (1862).

  Previously, this option could optionally take a host name in addition to the port number, but in MySQL Cluster Manager 1.1.1 and later the host name is no longer accepted.

• --manager-username=user_name

  The option serves the following two purposes:

  • Sets the user name for an mcm client to connect to the mcmd agent. If the option is not specified, the default value of mcmd is used. If the option is specified with another value, the client must supply it using the --user client option when trying to connect to the agent.

    The password for using this user name to connect to the agent is set with the --manager-password option.

  • Sets a user name for the MySQL account to be used by the mcmd agent to access the SQL nodes. If the option is not specified, the default value of mcmd is used.

    When an SQL node is initialized, the mcmd agent creates a new MySQL user account on it using the user name set by the option and the password set by the --manager-password option. This account is created with all privileges on the MySQL server including the granting of privileges. In other words, it is created as if you had executed GRANT ALL PRIVILEGES ON *.* ... WITH GRANT OPTION in the mysql client. The existing MySQL root account is not altered in such cases, and the default test database is preserved.

• --manager-password=password

  The option serves the following two purposes:

  • Sets the user password for an mcm client to connect to the mcmd agent with the user name set by --manager-username. If the option is not specified, the default value of super is used. If the option is specified with another value, the client must supply it using the --password client option when trying to connect to the agent.

  • Sets a password for the MySQL account to be used by the mcmd agent to access the SQL nodes. If the option is not specified, the default value of super is used.

    When an SQL node is initialized, the mcmd agent creates a new MySQL user account on it using the user name set by the --manager-username option and the password set by this option. See descriptions of --manager-username for more details about the account.

• --max-open-files=#

  Command-Line Format	--max-open-files=#
  Type	Numeric
  Default Value	1
  Minimum Value	1
  Maximum Value	[system dependent]

  Set the maximum number of open files (as with ulimit -n).

• --pid-file=file

  Command-Line Format	--pid-file=file_name
  Type	File name
  Default Value	mcmd.pid

  Set the name and path to a process ID (.pid) file. Not normally used or needed. This option is not supported on Windows systems.

• --plugin-dir

  Command-Line Format	--plugin-dir=dir_name
  Type	Directory name
  Default Value	lib/mcmd

  Set the directory to search for plugins. The default is lib/mcmd, in the MySQL Cluster Manager installation directory; normally there is no need to change this.

• --plugins

  Command-Line Format	--plugins=list
  Type	Directory name
  Default Value	manager

  Specify a list of plugins to be loaded on startup. To enable MySQL Cluster Manager, this list must include manager (the default value). Please be aware that we currently do not test MySQL Cluster Manager with any values for plugins other than manager. Therefore, we recommend using the default value in a production setting.

• --verbose-shutdown

  Command-Line Format	--verbose-shutdown

  Force mcmd to log the exit code whenever shutting down, regardless of the reason.

• --version, -V

  Command-Line Format	--version

  Display version information and exit. Output may vary according to the MySQL Cluster Manager software version, operating platform, and versions of libraries used on your system, but should closely resemble what is shown here, with the first line of output containing the MySQL Cluster Manager release number (emphasized text):

  $> mcmd  --version
  MySQL Cluster Manager 1.4.8 (64bit)
    chassis: 0.8.5.15734304
    glib2: 2.44.0
    libevent: 2.1.11-stable
  -- modules
    manager: 1.4.8

• --xcom-port

  Command-Line Format	--xcom-port=#
  Type	Numeric
  Default Value	18620
  Minimum Value	1
  Maximum Value	65535

  Allows you to specify the XCOM port. The default in 18620.