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


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

4.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 4.3, “Starting the MySQL Cluster Manager Client”, and Chapter 5, 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. (Some exceptions include the --config and --bootstrap options, which, if used, must be specified on the command line, and which are mutually exclusive with one another; also, filename and level (for logger) can only be set in the configuration file.) For example, you can set the user name for an mcm client to connect to the agent in either one of the following two ways:

  • Include --mcmd-user=johndoe on the command line when invoking mcmd.

    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:

    mcmd_user=johndoe

    When used in the configuration file, the name of the option should not be prefixed with any other characters. Hyphens in the option names should be changed to underscores. 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:

    #mcmd_user=johndoe

    The format of the configuration file follows that of the MySQL Router configuration file; see Configuration File Syntax for an explanation of the file format.

The following table contains a summary of agent options that are read on startup by mcmd. More detailed information about each of these options can be found in the option descriptions following the table.

Table 4.1 MySQL Cluster Manager Agent (mcmd) Option Summary

Name Cmd Cnf Srvr Stat Scope Dyn 8.0
bind-port Yes Yes Yes
bootstrap Yes Yes
config Yes Yes
copy-port Yes Yes Yes
data-folder Yes Yes Yes
extra-config Yes Yes
filename Yes Yes
help Yes Yes
initial Yes Yes
level Yes Yes
logging_folder Yes Yes
mcmd_password Yes Yes
mcmd-user Yes Yes Yes
pid-file Yes Yes Yes
version Yes Yes
xcom-port Yes Yes Yes

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.

  • --bind-port=#

    Command-Line Format --bind-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).

    When set in the configuration file, the option should be put inside the [mcmd] section.

  • --bootstrap, -B

    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.

  • --config=filename, -c

    Command-Line Format --config=file_name
    Type File name
    Default Value mcmd.conf, in the installation directory of MySQL Cluster Manager

    Set the file from which to read configuration options. mcmd.conf in the installation directory of MySQL Cluster Manager is the first default location mcmd looks for the file. See Section 3.4, “MySQL Cluster Manager Configuration File” for more information.

  • --copy-port

    Command-Line Format --copy-port=port
    Type Numeric
    Default Value 0

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

    When set in the configuration file, the option should be put inside the [mcmd] section.

  • --data-folder=dir_name, -d dir_name

    Command-Line Format --data-folder=dir_name
    Type Directory name
    Default Value mcm_data in the parent directory of the MySQL Cluster Manager installation directory

    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.

    The default location is mcm_data in the parent directory of the MySQL Cluster Manager installation directory. 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 data-folder 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 --data-folder option; see exceptions in, for example, Section 4.8, “Restoring a MySQL Cluster Manager Agent with Data from Other Agents” and Section 4.7, “Backing Up and Restoring MySQL Cluster Manager Agents”.

    When set in the configuration file, the option should be put inside the [DEFAULT] section.

  • --extra-config=filename , -a

    Command-Line Format --extra-config=file_name
    Type File name

    Read this file after configuration files are read from either default locations or from the location specified by the --config option. Multiple --extra-config options can be passed, and the files are loaded in the order they are specified.

  • --help, -?

    Command-Line Format --help

    mcmd help output provides information on some file paths and all the program options; it also provides some usage examples of the mcmd command:

    $> mcmd --help
    MySQL Cluster Manager  v8.0.27-dev on linux-glibc2.12 (64-bit) (MySQL Enterprise - Commercial)
    Copyright (c) 2007, 2021, Oracle and/or its affiliates.
    
    Oracle is a registered trademark of Oracle Corporation and/or its
    affiliates. Other names may be trademarks of their respective
    owners.
    
    Configuration read from the following files in the given order (enclosed
    in parentheses means not available for reading):
      (/opt/mcm8.0.27/bin/.././mcmd.conf)
      (/opt/mcm8.0.27/bin/.././mcmd.ini)
      (/home/jonhdoe/.mcmd.conf)
      (/home/johnbdoe/.mcmd.ini)
    Plugins Path:
      /opt/mcm8.0.27/lib/mysqlrouter
    
    Default Log Directory:
      /opt
    
    Default Persistent Data Directory:
      /opt/mcm_data
    
    Default Runtime State Directory:
      /opt
    
    
    # Usage
    
    mcmd (-?|--help)
    
    mcmd (-V|--version)
    
    mcmd (-c|--config=<path>) [-a|--extra-config=<path>]
    
    mcmd (-B|--bootstrap)
    
    mcmd (-d|--data-folder=<directory>)
    
    mcmd (-i|--initial)
    
    mcmd --pid-file=<pidfile>
    
    mcmd --mcmd-user=<username>
    
    mcmd --bind-port=<portnumber>
    
    mcmd --copy-port=<portnumber>
    
    mcmd --xcom-port=<portnumber>
    
    # Options
    
      -B, --bootstrap
            Bootstrap a MySQL Cluster using MySQL Cluster Manager
      -c <path>, --config <path>
            Only read configuration from given file.
      -d <directory>, --data-folder <directory>
            Data directory for MySQL Cluster Manager.
      -a <path>, --extra-config <path>
            Read this file after configuration files are read from either
            default locations or from files specified by the --config
            option.
      -?, --help
            Display this help and exit.
      -i, --initial
            Reinitialize configuration metadata directory
      --mcmd-user <username>
            The username used to access MySQL Cluster Manager
      --pid-file <pidfile>
            Path and filename of pid file
      -V, --version
            Display version information and exit.
      --bind-port <portnumber>
            Portnumber to use for mcmd.
      --copy-port <portnumber>
            Portnumber to use for file copying.
      --xcom-port <portnumber>
            Portnumber to use for XCOM.
    
    # Examples
    
    Bootstrap a cluster into system-wide installation
    
        sudo mcmd --bootstrap 
    
    Start mcmd as another user
    
        sudo mcmd --user=mcmd
    
    Bootstrap a cluster with a specified mcm_data directory
    
        mcmd --bootstrap -d my_mcm_data
  • --initial, -i

    Command-Line Format --initial

    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.

  • filename=filename

    Type File name
    Default Value mcmd.log

    Set the name of the file to write the log to. The option can only be set in the [logger] section of the configuration file, not on the command line. The default is mcmd.log, located in the same directory where the MySQL Cluster Manager installation directory is found. The location of this file can be overridden with the logging_folder option.

  • logging_folder=dir_name

    Type Directory name
    Default Value The parent directory of the MySQL Cluster Manager installation directory

    Path to the mcmd log file directory. The option can only be set in the [DEFAULT] section of the configuration file, not on the command line. The default is the parent directory of the MySQL Cluster Manager installation directory.

  • level=level

    Type Enumeration
    Default Value info
    Valid Values

    critical

    error

    warning

    info

    note

    debug

    Sets the mcmd log severity level. The option can only be set in the [logger] section of configuration file, not on the command line. Possible values for this option and their descriptions are listed in Table 4.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. info 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 4.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
    info Messages on main events of the site and from command execution (default)
    note 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.

    While the setting of the level option is applied only to the host whose mcmd agent uses the option, the change log-level client command can be used to apply the logging level to an entire management site or to specific hosts.

  • --mcmd-user=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 mcmd_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 mcmd_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.

    When set in the configuration file, the option should be put inside the [mcmd] section.

  • mcmd_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 --mcmd-user. 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 --mcmd-user option and the password set by this option. See descriptions of --mcmd-user for more details about the account.

    When set in the configuration file, the option should be put inside the [mcmd] section.

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

    When set in the configuration file, the option should be put inside the [DEFAULT] section.

  • --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  v8.0.27 on linux-glibc2.12 (64-bit) (MySQL Enterprise - Commercial)
  • --xcom-port

    Command-Line Format --xcom-port=port
    Type Numeric
    Default Value 18620

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

    When set in the configuration file, the option should be put inside the [mcmd] section.