Documentation Home
MySQL Cluster Manager 1.4 User Manual
Related Documentation Download this Manual
PDF (US Ltr) - 1.8Mb
PDF (A4) - 1.8Mb


MySQL Cluster Manager 1.4 User Manual  /  Using MySQL Cluster Manager  /  mcmd, the MySQL Cluster Manager Agent

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.