MYSQL_CONFIG_EDIT(1)

NAME
mysql_config_editor - configure authentication information for connecting to MySQL server

SYNOPSIS

mysql_config_editor options command

DESCRIPTION

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.3.3, “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:

    • help

    Display a help message and exit.

    • print [options]

    Print the contents of .mylogin.cnf in unencrypted form. Passwords are displayed as *****.

    The print command takes these options:

        • --all

        Print all login paths.

        • --login-path=name

        Print the named login path.

    If no login path is specified, the default path name is client. If both --all and --login-path are given, --all takes precedence.

    • remove [options]

    Remove a login path from the .mylogin.cnf file.

    The remove command takes these options:

        • --host

        Remove the host name from the login path.

        • --login-path=name

        The login path to remove. If this option is not given, the default path name is client.

        • --password

        Remove the password from the login path.

        • --port

        Remove the TCP/IP port number from the login path.

        • --socket

        Remove the Unix socket file name from the login path.

        • --user

        Remove the user name from the login path.

    The --host, --user, and --password options are supported for the remove command as of MySQL 5.6.9. The --port and --socket options are supported for the remove command as of MySQL 5.6.11

    The remove command removes from the login path only such values as are specified with the --host, --password, --port, --socket, and --user options. If none of them is given, remove removes the entire login path. For example, this command removes only the user value from the client login path rather than the entire client login path:

        mysql_config_editor remove --login-path=client --user

    • reset

    Empty the contents of the .mylogin.cnf file. The file is created if it does not exist.

    • set [options]

    Write a login path to the .mylogin.cnf file.

    The set command takes these options:

        • --host=host_name

        The host name to write to the login path.

        • --login-path=name

        The login path to create. If this option is not given, the default path name is client.

        • --password

        Prompt for a password to write to the login path.

        • --port=port_num

        The TCP/IP port number to write to the login path.

        • --socket=file_name

        The Unix socket file to write to the login path.

        • --user=user_name

        The user name to write to the login path.

    The --port and --socket options are supported for the set command as of MySQL 5.6.11

    The set command writes to the login path only such values as are specified with the --host, --password, --port, --socket, and --user options. If none of those options are given, mysql_config_editor writes the login path as an empty group.

    To specify an empty password, use the set command with the --password option, then press Enter at the password prompt. The resulting login path written to .mylogin.cnf will include a line like this:

        password =

    If the login path already exists in .mylogin.cnf, the set command replaces it. To ensure that this is what the user wants, mysql_config_editor prints a warning and prompts for confirmation. To suppress the warning and prompt, use the --skip-warn option.
        mysql_config_editor Options

mysql_config_editor supports the following options.

    • --help, -?

    Display a help message and exit. If preceded by a command name such as set or remove, displays information about that command.

    • --all

    For the print command, print all login paths in the login file.

    • --debug[=debug_options], -# debug_options

    Write a debugging log. A typical debug_options string is 'd:t:o,file_name'. The default is 'd:t:o,/tmp/mysql_config_editor.trace'.

    • --host=host_name, -h host_name

    For the set command, the host name to write to to the login path. For the remove command, removes the host name from the login path.

    • --login-path=name, -G name

    For the print, remove, and set commands, the login path to use in the .mylogin.cnf login file.

    Client programs also support the --login-path option, to enable users to specify which login path to use for connecting to a MySQL server. For client programs, --login-path must be the first option given, which is not true for mysql_config_editor. See Section 4.2.3.4, “Command-Line Options that Affect Option-File Handling”.

    • --password, -p

    For the set command, cause mysql_config_editor to prompt for a password and write the value entered by the user to the login path. After mysql_config_editor starts and displays the prompt, the user should type the password and press Enter. To prevent other users from seeing the password, mysql_config_editor does not echo it.

    This option does not permit a password value following the option name. That is, with mysql_config_editor, you never enter a password on the command line where it might be seen by other users. This differs from most other MySQL programs, which permit the password to be given on the command line as --password=pass_val or -ppass_val. (That practice is insecure and should be avoided, however.)

    For the remove command, removes the password from the login path.

    • --port=port_num, -P port_num

    For the set command, the TCP/IP port number to write to the login path. For the remove command, removes the port number from the login path.

    • --socket=file_name, -S file_name

    For the set command, the Unix socket file name to write to the login path. For the remove command, removes the socket file from the login path.

    • --user=user_name, -u user_name

    For the set command, the user name to write to the login path. For the remove command, removes the user name from the login path.

    • --verbose, -v

    Verbose mode. Print more information about what the program does.

    • --version, -V

    Display version information and exit.

    • --warn, -w

    For the set command, warn and prompt the user for confirmation if the command attempts to overwrite an existing login path. This option is enabled by default; use --skip-warn to disable it.

COPYRIGHT

Copyright © 1997, 2013, Oracle and/or its affiliates. All rights reserved.

This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited.

The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them to us in writing.

If this software or related documentation is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, the following notice is applicable:

U.S. GOVERNMENT RIGHTS Programs, software, databases, and related documentation and technical data delivered to U.S. Government customers are "commercial computer software" or "commercial technical data" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, the use, duplication, disclosure, modification, and adaptation shall be subject to the restrictions and license terms set forth in the applicable Government contract, and, to the extent applicable by the terms of the Government contract, the additional rights set forth in FAR 52.227-19, Commercial Computer Software License (December 2007). Oracle USA, Inc., 500 Oracle Parkway, Redwood City, CA 94065.

This software is developed for general use in a variety of information management applications. It is not developed or intended for use in any inherently dangerous applications, including applications which may create a risk of personal injury. If you use this software in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure the safe use of this software. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software in dangerous applications.

Oracle is a registered trademark of Oracle Corporation and/or its affiliates. MySQL is a trademark of Oracle Corporation and/or its affiliates, and shall not be used without Oracle's express written authorization. Other names may be trademarks of their respective owners.

This software and documentation may provide access to or information on content, products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party content, products, and services. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or services.

This document in any form, software or printed matter, contains proprietary information that is the exclusive property of Oracle. Your access to and use of this material is subject to the terms and conditions of your Oracle Software License and Service Agreement, which has been executed and with which you agree to comply. This document and information contained herein may not be disclosed, copied, reproduced, or distributed to anyone outside Oracle without prior written consent of Oracle or as specifically provided below. This document is not part of your license agreement nor can it be incorporated into any contractual agreement with Oracle or its subsidiaries or affiliates.

This documentation is NOT distributed under a GPL license. Use of this documentation is subject to the following terms:

You may create a printed copy of this documentation solely for your own personal use. Conversion to other formats is allowed as long as the actual content is not altered or edited in any way. You shall not publish or distribute this documentation in any form or on any media, except if you distribute the documentation in a manner similar to how Oracle disseminates it (that is, electronically for download on a Web site with the software) or on a CD-ROM or similar medium, provided however that the documentation is disseminated together with the software on the same medium. Any other use, such as any dissemination of printed copies or use of this documentation, in whole or in part, in another publication, requires the prior written consent from an authorized representative of Oracle. Oracle and/or its affiliates reserve any and all rights to this documentation not expressly granted above.

For more information on the terms of this license, or for details on how the MySQL documentation is built and produced, please visit MySQL Contact & Questions.

For additional licensing information, including licenses for third-party libraries used by MySQL products, see Preface and Legal Notices.

For help with using MySQL, please visit either the MySQL Forums or MySQL Mailing Lists where you can discuss your issues with other MySQL users.

For additional documentation on MySQL products, including translations of the documentation into other languages, and downloadable versions in variety of formats, including HTML and PDF formats, see the MySQL Documentation Library.

SEE ALSO
For more information, please refer to the MySQL Reference Manual, which may already be installed locally and which is also available online at http://dev.mysql.com/doc/.

AUTHOR
Oracle Corporation (http://dev.mysql.com/).