Documentation Home
MySQL Cluster Manager 1.3 User Manual
Related Documentation Download this Manual
PDF (US Ltr) - 1.8Mb
PDF (A4) - 1.8Mb
EPUB - 0.9Mb
HTML Download (TGZ) - 0.9Mb
HTML Download (Zip) - 0.9Mb


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

Format 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.
--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.
--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 cluster logging level.
--log-use-syslog Log to syslog.
--manager-directory Directory used for manager data storage.
--manager-password Password used for the manager account.
--manager-port Port for client to use when connecting to manager.
--manager-username User account name to run the manager under.
--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
    Permitted Values Type string
    Default [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
    Permitted Values Type directory name
    Default .

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

  • --bootstrap

    Command-Line Format --bootstrap
    Permitted Values Type boolean
    Default true

    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
    Permitted Values Type boolean
    Default true

    Run mcmd as a daemon.

  • --defaults-file=filename

    Command-Line Format --defaults-file=file_name
    Permitted Values Type file name
    Default 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=#
    Permitted Values Type numeric
    Default 1
    Min Value 1
    Max Value [system dependent]

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

  • --help, -?

    Command-Line Format --help
    Permitted Values Type boolean
    Default true

    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:

    shell> 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
    Permitted Values Type boolean
    Default true

    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
    Permitted Values Type boolean
    Default true

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

    shell> 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
    Permitted Values Type boolean
    Default true

    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
    Permitted Values Type boolean
    Default true

    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
    Permitted Values Type file name
    Default 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
    Permitted Values Type enumeration
    Default message
    Valid Values message
    debug
    critical
    error
    info
    warning

    Sets the cluster log event severity level; see MySQL Cluster Logging Management Commands, for definitions of the levels, which are the same as these except that ALERT is mapped to critical and the Unix syslog LOG_NOTICE level is used (and mapped to message). For additional information, see Event Reports Generated in MySQL Cluster.

    Possible values for this option are (any one of) debug, critical, error, info, message, and warning. message is the default.

    You should be aware that the debug, message, and info levels can result in rapid growth of the agent log, so for normal operations, you may prefer to set this to warning or error.

    You can also change the cluster logging level at runtime using the change log-level command in the mcm client. The option applies its setting to all hosts running on all sites, whereas change log-level is more flexible; its effects can be constrained to a specific management site, or to one or more hosts within that site.

  • --log-use-syslog

    Command-Line Format --log-use-syslog
    Permitted Values Type boolean
    Default true

    Write logging output to syslog.

  • --manager-directory=dir_name

    Command-Line Format --manager-directory=dir
    Permitted Values Type directory name
    Default /opt/mcm_data

    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 /opt/mcm_data. 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 checksum file from the manager-directory. Otherwise, the agent reads this file and raises a checksum error due to the now-empty rep directory.

  • --manager-password=password

    Command-Line Format --manager-password=password
    Permitted Values Type string
    Default 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
    Permitted Values Type numeric
    Default localhost: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
    Permitted Values Type string
    Default 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=#
    Permitted Values Type numeric
    Default 1
    Min Value 1
    Max Value [system dependent]

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

  • --pid-file=file

    Command-Line Format --pid-file=file_name
    Permitted Values Type file name
    Default 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
    Permitted Values Type directory name
    Default 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
    Permitted Values Type directory name
    Default

    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
    Permitted Values Type boolean
    Default true

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

  • --version, -V

    Command-Line Format --version
    Permitted Values Type boolean
    Default true

    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):

    shell> 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=port
    Permitted Values Type numeric
    Default 18620

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


User Comments
Sign Up Login You must be logged in to post a comment.