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
--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
--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
--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 noted as boolean need only be specified in order to take effect; you should not try to set a value for these.

• --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. This option is mutually exclusive with the --defaults-file option.

  Currently, any data stored in the default cluster mycluster is not preserved between cluster restarts.

• --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:
    -?, --help                          Show help options
    --help-all                          Show all help options
    --help-manager                      Show options for the manager-module
  
  manager-module
    --manager-port=<clientport>         Port to manage the cluster (default: 1862)
    --xcom-port=<xcomport>              Xcom port (default: 18620)
    --manager-username=<username>       Username to manage the cluster (default: mcmd)
    --manager-password=<password>       Password for the manager user-account (default: super)
    --bootstrap                         Bootstrap a default cluster on initial startup
    --manager-directory=<directory>     Path to managers config information
  
  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
    --manager-port=<clientport>         Port to manage the cluster (default: 1862)
    --xcom-port=<xcomport>              Xcom port (default: 18620)
    --manager-username=<username>       Username to manage the cluster (default: mcmd)
    --manager-password=<password>       Password for the manager user-account (default: super)
    --bootstrap                         Bootstrap a default cluster on initial startup
    --manager-directory=<directory>     Path to managers config information

• --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 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 MySQL Cluster Manager data files, the manager-directory also contains a rep directory in which MySQL Cluster data files for each MySQL Cluster under MySQL Cluster Manager control 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).

  However, in the event that an agent reaches an inconsistent state, it is possible to delete the contents of the rep directory, in which case the agent attempts to recover its repository from another agent. In such cases, you must also delete the repchksum file and the high_water_mark file from the manager-directory. Otherwise, the agent reads these files and raises errors due to the now-empty rep directory.

• --manager-password=password

  Command-Line Format	--manager-password=password
  Type	String
  Default Value	super

  Set a password to be used for the manager agent user account. The default is super.

  Using this option together with manager-username causes the creation of a MySQL user account, having the username and password specified using these two options. 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.

• --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

  Command-Line Format	--manager-username=name
  Type	String
  Default Value	mcmd

  Set a user name for the MySQL account to be used by the MySQL Cluster Manager agent. The default is mcmd.

  When used together with manager-password, this option also causes the creation of a new MySQL user account, having the user name and password specified using these two options. 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.

• --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 -V
  MySQL Cluster Manager 1.3.6 (64bit)
    chassis: mysql-proxy 0.8.3
    glib2: 2.16.6
    libevent: 1.4.13-stable
  -- modules
    manager: 1.3.6

• --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.