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


MySQL Cluster Manager 1.3 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
--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.