4.6.6 mysql_config_editor — MySQL Configuration Utility

The mysql_config_editor utility (available as of MySQL 5.6.6) enables you to store authentication credentials in an encrypted login file named .mylogin.cnf. The file location is the %APPDATA%\MySQL directory on Windows and the current user's home directory on non-Windows systems. The file can be read later by MySQL client programs to obtain authentication credentials for connecting to MySQL Server.

To specify an alternate file name, set the MYSQL_TEST_LOGIN_FILE environment variable. This variable is used by the mysql-test-run.pl testing utility, but also is recognized by mysql_config_editor and by MySQL clients such as mysql, mysqladmin, and so forth.

mysql_config_editor encrypts the .mylogin.cnf file so it cannot be read as clear text, and its contents when decrypted by client programs are used only in memory. In this way, passwords can be stored in a file in non-cleartext format and used later without ever needing to be exposed on the command line or in an environment variable. mysql_config_editor provides a print command that enables the user to display the file contents, but even in this case, password values are masked so as never to appear in a way that other users can see them.

The encryption used by mysql_config_editor prevents passwords from appearing in .mylogin.cnf as clear text and provides a measure of security by preventing inadvertent password exposure. For example, if you display a regular unencrypted my.cnf option file on the screen, any passwords it contains are visible for anyone to see. With .mylogin.cnf, that is not true. But the encryption used will not deter a determined attacker and you should not consider it unbreakable. A user who can gain system administration privileges on your machine to access your files could decrypt the .mylogin.cnf file with some effort.

The login file must be readable and writable to the current user, and inaccessible to other users. Otherwise, mysql_config_editor ignores it, and the file is not used by client programs, either. On Windows, this constraint does not apply; instead, the user must have access to the %APPDATA%\MySQL directory.

The unencrypted format of the .mylogin.cnf login file consists of option groups, similar to other option files. Each option group in .mylogin.cnf is called a login path, which is a group that permits only a limited set of options: host, user, and password. Think of a login path as a set of values that indicate the server host and the credentials for authenticating with the server. Here is an example:

[myloginpath]
user = myname
password = mypass
host = 127.0.0.1

When you invoke a client program to connect to the server, .mylogin.cnf is used in conjunction with other option files. Its precedence is higher than other option files, but less than options specified explicitly on the client command line. For information about the order in which option files are used, see Section 4.2.6, “Using Option Files”.

Invoke mysql_config_editor like this:

shell> mysql_config_editor [program_options] command [command_options]

program_options consists of general mysql_config_editor options. command indicates what command to perform, and command_options indicates any additional options needed by the command.

The command indicates what action to perform on the .mylogin.cnf login file. For example, set writes a login path to the file, remove removes a login path, and print displays login path contents. Any options given provide information to the command, such as the login path name and the values to use in the login path.

The position of the command name within the set of program arguments is significant. For example, these command lines have the same arguments, but produce different results:

mysql_config_editor --help set
mysql_config_editor set --help

The first command line displays general mysql_config_editor help, and ignores the set command. The second command line displays help for the set command.

Suppose that you want to establish two login paths named local and remote for connecting to the local MySQL server and a server on the host remote.example.com. You want to authenticate to the local server with a user name and password of localuser and localpass, and to the remote server with a user name and password of remoteuser and remotepass. To set up the login paths in the .mylogin.cnf file, use the following set commands. Enter each command on a single line, then enter the appropriate password when prompted.

shell> mysql_config_editor set --login-path=local
         --host=localhost --user=localuser --password
Enter password: enter password "localpass" here
shell> mysql_config_editor set --login-path=remote
         --host=remote.example.com --user=remoteuser --password
Enter password: enter password "remotepass" here

To see what mysql_config_editor wrote to the .mylogin.cnf file, use the print command:

shell> mysql_config_editor print --all
[local]
user = localuser
password = *****
host = localhost
[remote]
user = remoteuser
password = *****
host = remote.example.com

The print command displays each login path as a set of lines beginning with a group header indicating the login path name in square brackets, followed by the option values for the login path. Password values are masked and do not appear as clear text.

As shown by the preceding examples, the .mylogin.cnf file can contain multiple login paths. In this way, mysql_config_editor makes it easy to set up multiple personalities for connecting to different MySQL servers. Any of these can be selected by name later using the --login-path option when you invoke a client program. For example, to connect to the local server, use this command:

shell> mysql --login-path=local

To connect to the remote server, use this command:

shell> mysql --login-path=remote

When you use the set command with mysql_config_editor to create a login path, you need not specify all three possible option values (host name, user name, and password). Only those values given are written to the path. Any missing values required later can be specified when you invoke a client path to connect to the MySQL server, either in other option files or on the command line. Also, any options specified on the command line override those in option files, including the .mylogin.cnf file. For example, if the credentials in the remote login path also apply for the host remote2.example.com, you can connect to the server on that host like this:

shell> mysql --login-path=remote --host=remote2.example.com

The .mylogin.cnf file, if it exists, is read in all cases, even when the --no-defaults option is used. This permits passwords to be specified in a safer way than on the command line even if --no-defaults is present.

mysql_config_editor Commands

This section describes the permitted mysql_config_editor commands, and the interpretation of options that have a command-specific meaning. In addition, mysql_config_editor takes other options that can be used with any command, such as --verbose to produce more information as mysql_config_editor executes. This option may be helpful in diagnosing problems if an operation does not have the effect you expect. For a list of supported options, see mysql_config_editor Options.

mysql_config_editor supports these commands:

mysql_config_editor Options

mysql_config_editor supports the following options.

Table 4.13 mysql_config_editor Options

FormatDescriptionIntroduced
--allPrint all login paths 
--debug[=debug_options]Write a debugging log 
--helpDisplay help message and exit 
--host=host_nameHost to write to login file 
--login-path=nameLogin path name 
--passwordSolicit password to write to login file 
--port=port_numTCP/IP port number to write to login file5.6.11
--socket=pathThe Unix socket file name to write to login file5.6.11
--user=user_nameUser name to write to login file 
--verboseVerbose mode 
--versionDisplay version information and exit 
--warnWarn and solicit confirmation for overwriting login path