mysql_config_editor - configure authentication information for connecting to MySQL server
mysql_config_editor options command
MYSQL_CONFIG_EDIT(1) MySQL Database System 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.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.PP 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:
o help
Display a help message and exit.
o print [options]
Print the contents of .mylogin.cnf in unencrypted form. Passwords
are displayed as *****.
The print command takes these options:
o --all
Print all login paths.
o --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.
o remove [options]
Remove a login path from the .mylogin.cnf file.
The remove command takes these options:
o --host
Remove the host name from the login path.
o --login-path=name
The login path to remove. If this option is not given, the
default path name is client.
o --password
Remove the password from the login path.
o --port
Remove the TCP/IP port number from the login path.
o --socket
Remove the Unix socket file name from the login path.
o --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
o reset
Empty the contents of the .mylogin.cnf file. The file is created if
it does not exist.
o set [options]
Write a login path to the .mylogin.cnf file.
The set command takes these options:
o --host=host_name
The host name to write to the login path.
o --login-path=name
The login path to create. If this option is not given, the
default path name is client.
o --password
Prompt for a password to write to the login path.
o --port=port_num
The TCP/IP port number to write to the login path.
o --socket=file_name
The Unix socket file to write to the login path.
o --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.PP mysql_config_editor supports the
following options.
o --help, -?
Display a help message and exit. If preceded by a command name such
as set or remove, displays information about that command.
o --all
For the print command, print all login paths in the login file.
o --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.
o --host=host_name, -h host_name
For the set command, the host name to write to the login path. For
the remove command, removes the host name from the login path.
o --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.7, "Command-Line Options that Affect Option-File
Handling".
o --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.
o --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.
o --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.
o --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.
o --verbose, -v
Verbose mode. Print more information about what the program does.
o --version, -V
Display version information and exit.
o --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 (C) 1997, 2014, Oracle and/or its affiliates. All rights
reserved.
This documentation is free software; you can redistribute it and/or
modify it only under the terms of the GNU General Public License as
published by the Free Software Foundation; version 2 of the License.
This documentation is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details.
You should have received a copy of the GNU General Public License along
with the program; if not, write to the Free Software Foundation, Inc.,
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA or see
http://www.gnu.org/licenses/.
ATTRIBUTES
See attributes(5) for descriptions of the following attributes:
+---------------+--------------------------+
|ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+---------------+--------------------------+
|Availability | database/mysql-56/client |
+---------------+--------------------------+
|Stability | Uncommitted |
+---------------+--------------------------+
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/).
NOTES
This software was built from source available at
https://java.net/projects/solaris-userland. The original community
source was downloaded from
http://downloads.mysql.com/archives/mysql-5.6/mysql-5.6.21.tar.gz
Further information about this software can be found on the open source
community website at http://dev.mysql.com/.
MySQL 5.6 09/11/2014 MYSQL_CONFIG_EDIT(1)