~ubuntu-branches/ubuntu/wily/mysql-5.6/wily

.\"      Date: 05/05/2015

.TH "\FBMYSQL_CONFIG_EDIT" "1" "05/05/2015" "MySQL 5\&.6" "MySQL Database System"

utility (available as of MySQL 5\&.6\&.6) enables you to store authentication credentials in an encrypted login path file named

The unencrypted format of the

\&.mylogin\&.cnf

login path file consists of option groups, similar to other option files\&. Each option group in

\&.mylogin\&.cnf

is called a

\(lqlogin path,\(rq

which is a group that permits only certain options:

\fBhost\fR,

\fBuser\fR,

\fBpassword\fR,

\fBport\fR

and

\fBsocket\fR\&. Think of a login path option group as a set of values that indicate the server host and the options for connecting to the MySQL server there\&. Here is an unencrypted example:

.sp

.if n \{\

.RS 4

.\}

.nf

[client]

user = mydefaultname

password = mydefaultpass

host = 127\&.0\&.0\&.1

[mypath]

user = myothername

password = myotherpass

host = localhost

.fi

.if n \{\

.RE

.\}

.PP

When you invoke a client program to connect to the server, the client uses

\&.mylogin\&.cnf

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, \(lqUsing Option Files\(rq\&.

.\" MYSQL_TEST_LOGIN_FILE environment variable

.\" environment variable: MYSQL_TEST_LOGIN_FILE

.PP

To specify an alternate login path file name, set the

environment variable\&. This variable is recognized by

\fBmysql_config_editor\fR, by standard MySQL clients (\fBmysql\fR,

\fBmysqladmin\fR, and so forth), and by the

testing utility\&.

.PP

Programs use groups in the login path file as follows:

.sp

.RS 4

.ie n \{\

\h'-04'\(bu\h'+03'\c

.\}

.el \{\

.sp -1

.IP \(bu 2.3

.\}

\fBmysql_config_editor\fR

operates on the

client

login path by default if you specify no

\fB\-\-login\-path=\fR\fB\fIname\fR\fR

option to indicate explicitly which login path to use\&.

.RE

.sp

.RS 4

.ie n \{\

\h'-04'\(bu\h'+03'\c

.\}

.el \{\

.sp -1

.IP \(bu 2.3

.\}

Without a

\fB\-\-login\-path\fR

option, client programs read the same option groups from the login path file that they read from other option files\&. Consider this command:

.sp

.if n \{\

.RS 4

.\}

.nf

shell> \fBmysql\fR

.fi

.if n \{\

.RE

.\}

.sp

By default, the

\fBmysql\fR

client reads the

[client]

and

[mysql]

groups from other option files, so it reads them from the login path file as well\&.

.RE

.sp

.RS 4

.ie n \{\

\h'-04'\(bu\h'+03'\c

.\}

.el \{\

.sp -1

.IP \(bu 2.3

.\}

With a

\fB\-\-login\-path\fR

option, client programs additionally read the named login path from the login path ile\&. The option groups read from other option files remain the same\&. Consider this command:

.sp

.if n \{\

.RS 4

.\}

.nf

shell> \fBmysql \-\-login\-path=mypath\fR

.fi

.if n \{\

.RE

.\}

.sp

The

\fBmysql\fR

client reads

[client]

and

[mysql]

from other option files, and

[client],

[mysql], and

[mypath]

from the login path file\&.

.RE

.sp

.RS 4

.ie n \{\

\h'-04'\(bu\h'+03'\c

.\}

.el \{\

.sp -1

.IP \(bu 2.3

.\}

Client programs read the login path file even when the

\fB\-\-no\-defaults\fR

option is used\&. This permits passwords to be specified in a safer way than on the command line even if

\fB\-\-no\-defaults\fR

is present\&.

.RE

file so it cannot be read as cleartext, 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\&.

command for displaying the login path 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\&.

as cleartext and provides a measure of security by preventing inadvertent password exposure\&. For example, if you display a regular unencrypted

The login path file must be readable and writable to the current user, and inaccessible to other users\&. Otherwise,

ignores it, and client programs do not use it, either\&. On Windows, this constraint does not apply; instead, the user must have access to the

\fBmysql_config_editor\fR

If the login path file does not exist,

\fBmysql_config_editor\fR

creates it\&.

.PP

Command arguments are given as follows:

.sp

.RS 4

.ie n \{\

\h'-04'\(bu\h'+03'\c

.\}

.el \{\

.sp -1

.IP \(bu 2.3

.\}

.RE

.sp

.RS 4

.ie n \{\

\h'-04'\(bu\h'+03'\c

.\}

.el \{\

.sp -1

.IP \(bu 2.3

.\}

indicates what action to perform on the

login path file\&. For example,

displays login path contents\&.

.RE

.sp

.RS 4

.ie n \{\

\h'-04'\(bu\h'+03'\c

.\}

.el \{\

.sp -1

.IP \(bu 2.3

.\}

\fIcommand_options\fR

indicates any additional options specific to the command, such as the login path name and the values to use in the login path\&.

.RE

shell> \fBmysql_config_editor \-\-help set\fR

shell> \fBmysql_config_editor set \-\-help\fR

The first command line displays a general

help message, and ignores the

command\&. The second command line displays a help message specific to the

Suppose that you want to establish a

client

login path that defines your default connection parameters, and an additional login path named

for connecting to the MySQL server the host

remote\&.example\&.com\&. You want to log in as follows:

.sp

.RS 4

.ie n \{\

\h'-04'\(bu\h'+03'\c

.\}

.el \{\

.sp -1

.IP \(bu 2.3

.\}

By default, to the local server with a user name and password of

localpass

.RE

.sp

.RS 4

.ie n \{\

\h'-04'\(bu\h'+03'\c

.\}

.el \{\

.sp -1

.IP \(bu 2.3

.\}

To the remote server with a user name and password of

remotepass

.RE

.PP

To set up the login paths in the

commands\&. Enter each command on a single line, and enter the appropriate passwords when prompted:

shell> \fBmysql_config_editor set \-\-login\-path=client

\fBmysql_config_editor\fR

uses the

client

login path by default, so the

\fB\-\-login\-path=client\fR

option can be omitted from the first command without changing its effect\&.

.PP

writes to the

[client]

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 cleartext\&.

.PP

If you do not specify

\fB\-\-all\fR

to display all login paths or

\fB\-\-login\-path=\fR\fB\fIname\fR\fR

to display a named login path, the

print

command displays the

client

login path by default, if there is one\&.

.PP

As shown by the preceding example, the login path file can contain multiple login paths\&. In this way,

for connecting to different MySQL servers, or for connecting to a given server using different accounts\&. Any of these can be selected by name later using the

option when you invoke a client program\&. For example, to connect to the remote server, use this command:

Here,

\fBmysql\fR

reads the

[client]

and

[mysql]

option groups from other option files, and the

[client],

[mysql], and

[remote]

groups from the login path file\&.

.PP

To connect to the local server, use this command:

.sp

.if n \{\

.RS 4

.\}

.nf

shell> \fBmysql \-\-login\-path=client\fR

.fi

.if n \{\

.RE

.\}

.PP

Because

\fBmysql\fR

reads the

client

and

mysql

login paths by default, the

\fB\-\-login\-path\fR

option does not add anything in this case\&. That command is equivalent to this one:

.sp

.if n \{\

.RS 4

.\}

.nf

shell> \fBmysql\fR

.fi

.if n \{\

.RE

.\}

.PP

Options read from the login path file take precedence over options read from other option files\&. Options read from login path groups appearing later in the login path file take precedence over options read from groups appearing earlier in the file\&.

.PP

\fBmysql_config_editor\fR

adds login paths to the login path file in the order you create them, so you should create more general login paths first and more specific paths later\&. If you need to move a login path within the file, you can remove it, then recreate it to add it to the end\&.

.PP

to create a login path, you need not specify all possible option values (host name, user name, password, port, socket)\&. 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\&. Any options specified on the command line override those specified in the login path file or other option files\&. For example, if the credentials in the

remote2\&.example\&.com, connect to the server on that host like this:

.sp

mysql_config_editor General Options.PP

\fBmysql_config_editor\fR

supports the following general options, which may be used preceding any command named on the command line\&. For descriptions of command\-specific options, see

mysql_config_editor Commands and Command-Specific Options\&.

.sp

.RS 4

.ie n \{\

\h'-04'\(bu\h'+03'\c

.\}

.el \{\

.sp -1

.IP \(bu 2.3

.\}

.\" mysql_config_editor: help option

.\" help option: mysql_config_editor

\fB\-\-help\fR,

\fB\-?\fR

.sp

Display a general help message and exit\&.

.sp

To see a command\-specific help message, invoke

\fBmysql_config_editor\fR

as follows, where

\fIcommand\fR

is a command other than

help:

.sp

.if n \{\

.RS 4

.\}

.nf

shell> \fBmysql_config_editor \fR\fB\fIcommand\fR\fR\fB \-\-help\fR

.fi

.if n \{\

.RE

.\}

.RE

.sp

.RS 4

.ie n \{\

\h'-04'\(bu\h'+03'\c

.\}

.el \{\

.sp -1

.IP \(bu 2.3

.\}

.\" mysql_config_editor: debug option

.\" debug option: mysql_config_editor

\fB\-\-debug[=\fR\fB\fIdebug_options\fR\fR\fB]\fR,

\fB\-# \fR\fB\fIdebug_options\fR\fR

.sp

Write a debugging log\&. A typical

\fIdebug_options\fR

string is

d:t:o,\fIfile_name\fR\&. The default is

d:t:o,/tmp/mysql_config_editor\&.trace\&.

.RE

.sp

.RS 4

.ie n \{\

\h'-04'\(bu\h'+03'\c

.\}

.el \{\

.sp -1

.IP \(bu 2.3

.\}

.\" mysql_config_editor: verbose option

.\" verbose option: mysql_config_editor

\fB\-\-verbose\fR,

\fB\-v\fR

.sp

Verbose mode\&. Print more information about what the program does\&. This option may be helpful in diagnosing problems if an operation does not have the effect you expect\&.

.RE

.sp

.RS 4

.ie n \{\

\h'-04'\(bu\h'+03'\c

.\}

.el \{\

.sp -1

.IP \(bu 2.3

.\}

.\" mysql_config_editor: version option

.\" version option: mysql_config_editor

\fB\-\-version\fR,

\fB\-V\fR

.sp

Display version information and exit\&.

.RE

mysql_config_editor Commands and Command\-Specific Options.PP

commands, and, for each one, the command\-specific options permitted following the command name on the command line\&.

.PP

In addition,

\fBmysql_config_editor\fR

supports general options that can be used preceding any command\&. For descriptions of these options, see

mysql_config_editor General Options\&.

Display a general help message and exit\&. This command takes no following options\&.

.sp

To see a command\-specific help message, invoke

\fBmysql_config_editor\fR

as follows, where

\fIcommand\fR

is a command other than

help:

.sp

.if n \{\

.RS 4

.\}

.nf

shell> \fBmysql_config_editor \fR\fB\fIcommand\fR\fR\fB \-\-help\fR

.fi

.if n \{\

.RE

.\}

Print the contents of the login path file in unencrypted form, with the exception that passwords are displayed as

The default login path name is

client

if no login path is named\&. If both

.sp

The

print

command permits these options following the command name:

.sp

.RS 4

.ie n \{\

\h'-04'\(bu\h'+03'\c

.\}

.el \{\

.sp -1

.IP \(bu 2.3

.\}

\fB\-\-help\fR,

\fB\-?\fR

.sp

Display a help message for the

print

command and exit\&.

.sp

To see a general help message, use

\fBmysql_config_editor \-\-help\fR\&.

.RE

.sp

.RS 4

.ie n \{\

\h'-04'\(bu\h'+03'\c

.\}

.el \{\

.sp -1

.IP \(bu 2.3

.\}

\fB\-\-all\fR

.sp

Print the contents of all login paths in the login path file\&.

.RE

.sp

.RS 4

.ie n \{\

\h'-04'\(bu\h'+03'\c

.\}

.el \{\

.sp -1

.IP \(bu 2.3

.\}

\fB\-\-login\-path=\fR\fB\fIname\fR\fR,

\fB\-G \fR\fB\fIname\fR\fR

.sp

Print the contents of the named login path\&.

.RE

Remove a login path from the login path file, or modify a login path by removing options from it\&.

.sp

This command removes from the login path only such options as are specified with the

options\&. If none of those options are given,

option from the

mypath

mypath

login path:

.sp

.if n \{\

.RS 4

.\}

.nf

shell> \fBmysql_config_editor remove \-\-login\-path=mypath \-\-user\fR

.fi

.if n \{\

.RE

.\}

.sp

This command removes the entire

mypath

login path:

.sp

.if n \{\

.RS 4

.\}

.nf

shell> \fBmysql_config_editor remove \-\-login\-path=mypath\fR

.fi

.if n \{\

.RE

.\}

.sp

The

remove

command permits these options following the command name:

.sp

.RS 4

.ie n \{\

\h'-04'\(bu\h'+03'\c

.\}

.el \{\

.sp -1

.IP \(bu 2.3

.\}

\fB\-\-help\fR,

\fB\-?\fR

.sp

Display a help message for the

remove

command and exit\&.

.sp

To see a general help message, use

\fBmysql_config_editor \-\-help\fR\&.

.RE

.sp

.RS 4

.ie n \{\

\h'-04'\(bu\h'+03'\c

.\}

.el \{\

.sp -1

.IP \(bu 2.3

.\}

\fB\-\-host\fR,

\fB\-h\fR

.sp

Remove the host name from the login path\&. This option was added in MySQL 5\&.6\&.9\&.

.RE

.sp

.RS 4

.ie n \{\

\h'-04'\(bu\h'+03'\c

.\}

.el \{\

.sp -1

.IP \(bu 2.3

.\}

\fB\-\-login\-path=\fR\fB\fIname\fR\fR,

\fB\-G \fR\fB\fIname\fR\fR

.sp

The login path to remove or modify\&. The default login path name is

if this option is not given\&.

.RE

.sp

.RS 4

.ie n \{\

\h'-04'\(bu\h'+03'\c

.\}

.el \{\

.sp -1

.IP \(bu 2.3

.\}

\fB\-\-password\fR,

\fB\-p\fR

.sp

Remove the password from the login path\&. This option was added in MySQL 5\&.6\&.9\&.

.RE

.sp

.RS 4

.ie n \{\

\h'-04'\(bu\h'+03'\c

.\}

.el \{\

.sp -1

.IP \(bu 2.3

.\}

\fB\-\-port\fR,

\fB\-P\fR

.sp

Remove the TCP/IP port number from the login path\&. This option was added in MySQL 5\&.6\&.11\&.

.RE

.sp

.RS 4

.ie n \{\

\h'-04'\(bu\h'+03'\c

.\}

.el \{\

.sp -1

.IP \(bu 2.3

.\}

\fB\-\-socket\fR,

\fB\-S\fR

.sp

Remove the Unix socket file name from the login path\&. This option was added in MySQL 5\&.6\&.11\&.

.RE

.sp

.RS 4

.ie n \{\

\h'-04'\(bu\h'+03'\c

.\}

.el \{\

.sp -1

.IP \(bu 2.3

.\}

\fB\-\-user\fR,

\fB\-u\fR

.sp

Remove the user name from the login path\&. This option was added in MySQL 5\&.6\&.9\&.

.RE

.sp

.RS 4

.ie n \{\

\h'-04'\(bu\h'+03'\c

.\}

.el \{\

.sp -1

.IP \(bu 2.3

.\}

\fB\-\-warn\fR,

\fB\-w\fR

.sp

Warn and prompt the user for confirmation if the command attempts to remove the default login path (client) and

\fB\-\-login\-path=client\fR

was not specified\&. This option is enabled by default; use

\fB\-\-skip\-warn\fR

to disable it\&.

.RE

.RE

.sp

.RS 4

.ie n \{\

\h'-04'\(bu\h'+03'\c

.\}

.el \{\

.sp -1

.IP \(bu 2.3

.\}

reset [\fIoptions\fR]

.sp

Empty the contents of the login path file\&.

.sp

The

reset

command permits these options following the command name:

.sp

.RS 4

.ie n \{\

\h'-04'\(bu\h'+03'\c

.\}

.el \{\

.sp -1

.IP \(bu 2.3

.\}

\fB\-\-help\fR,

\fB\-?\fR

.sp

Display a help message for the

reset

command and exit\&.

.sp

To see a general help message, use

\fBmysql_config_editor \-\-help\fR\&.

.RE

Write a login path to the login path file\&.

.sp

This command writes to the login path only such options as are specified with the

The

set

command permits these options following the command name:

Display a help message for the

command and exit\&.

.sp

To see a general help message, use

\fBmysql_config_editor \-\-help\fR\&.

.RE

.sp

.RS 4

.ie n \{\

\h'-04'\(bu\h'+03'\c

.\}

.el \{\

.sp -1

.IP \(bu 2.3

.\}

The host name to write to the login path\&.