1MYSQL_CONFIG_EDITOR(1)       MySQL Database System      MYSQL_CONFIG_EDITOR(1)
2
3
4

NAME

6       mysql_config_editor - configure authentication information for
7       connecting to MySQL server
8

SYNOPSIS

10       mysql_config_editor options command
11

DESCRIPTION

13       The mysql_config_editor utility enables you to store authentication
14       credentials in an obfuscated login path file named .mylogin.cnf. The
15       file location is the %APPDATA%\MySQL directory on Windows and the
16       current user's home directory on non-Windows systems. The file can be
17       read later by MySQL client programs to obtain authentication
18       credentials for connecting to MySQL Server.
19
20       The unobfuscated format of the .mylogin.cnf login path file consists of
21       option groups, similar to other option files. Each option group in
22       .mylogin.cnf is called a “login path,” which is a group that permits
23       only certain options: host, user, password, port and socket. Think of a
24       login path option group as a set of options that specify which MySQL
25       server to connect to and which account to authenticate as. Here is an
26       unobfuscated example:
27
28           [client]
29           user = mydefaultname
30           password = mydefaultpass
31           host = 127.0.0.1
32           [mypath]
33           user = myothername
34           password = myotherpass
35           host = localhost
36
37       When you invoke a client program to connect to the server, the client
38       uses .mylogin.cnf in conjunction with other option files. Its
39       precedence is higher than other option files, but less than options
40       specified explicitly on the client command line. For information about
41       the order in which option files are used, see Section 4.2.2.2, “Using
42       Option Files”.
43
44       To specify an alternate login path file name, set the
45       MYSQL_TEST_LOGIN_FILE environment variable. This variable is recognized
46       by mysql_config_editor, by standard MySQL clients (mysql, mysqladmin,
47       and so forth), and by the mysql-test-run.pl testing utility.
48
49       Programs use groups in the login path file as follows:
50
51       ·   mysql_config_editor operates on the client login path by default if
52           you specify no --login-path=name option to indicate explicitly
53           which login path to use.
54
55       ·   Without a --login-path option, client programs read the same option
56           groups from the login path file that they read from other option
57           files. Consider this command:
58
59               shell> mysql
60
61           By default, the mysql client reads the [client] and [mysql] groups
62           from other option files, so it reads them from the login path file
63           as well.
64
65       ·   With a --login-path option, client programs additionally read the
66           named login path from the login path file. The option groups read
67           from other option files remain the same. Consider this command:
68
69               shell> mysql --login-path=mypath
70
71           The mysql client reads [client] and [mysql] from other option
72           files, and [client], [mysql], and [mypath] from the login path
73           file.
74
75       ·   Client programs read the login path file even when the
76           --no-defaults option is used. This permits passwords to be
77           specified in a safer way than on the command line even if
78           --no-defaults is present.
79
80       mysql_config_editor obfuscates the .mylogin.cnf file so it cannot be
81       read as cleartext, and its contents when unobfuscated by client
82       programs are used only in memory. In this way, passwords can be stored
83       in a file in non-cleartext format and used later without ever needing
84       to be exposed on the command line or in an environment variable.
85       mysql_config_editor provides a print command for displaying the login
86       path file contents, but even in this case, password values are masked
87       so as never to appear in a way that other users can see them.
88
89       The obfuscation used by mysql_config_editor prevents passwords from
90       appearing in .mylogin.cnf as cleartext and provides a measure of
91       security by preventing inadvertent password exposure. For example, if
92       you display a regular unobfuscated my.cnf option file on the screen,
93       any passwords it contains are visible for anyone to see. With
94       .mylogin.cnf, that is not true, but the obfuscation used is not likely
95       to deter a determined attacker and you should not consider it
96       unbreakable. A user who can gain system administration privileges on
97       your machine to access your files could unobfuscate the .mylogin.cnf
98       file with some effort.
99
100       The login path file must be readable and writable to the current user,
101       and inaccessible to other users. Otherwise, mysql_config_editor ignores
102       it, and client programs do not use it, either.
103
104       Invoke mysql_config_editor like this:
105
106           shell> mysql_config_editor [program_options] command [command_options]
107
108       If the login path file does not exist, mysql_config_editor creates it.
109
110       Command arguments are given as follows:
111
112       ·   program_options consists of general mysql_config_editor options.
113
114       ·   command indicates what action to perform on the .mylogin.cnf login
115           path file. For example, set writes a login path to the file, remove
116           removes a login path, and print displays login path contents.
117
118       ·   command_options indicates any additional options specific to the
119           command, such as the login path name and the values to use in the
120           login path.
121
122       The position of the command name within the set of program arguments is
123       significant. For example, these command lines have the same arguments,
124       but produce different results:
125
126           shell> mysql_config_editor --help set
127           shell> mysql_config_editor set --help
128
129       The first command line displays a general mysql_config_editor help
130       message, and ignores the set command. The second command line displays
131       a help message specific to the set command.
132
133       Suppose that you want to establish a client login path that defines
134       your default connection parameters, and an additional login path named
135       remote for connecting to the MySQL server the host remote.example.com.
136       You want to log in as follows:
137
138       ·   By default, to the local server with a user name and password of
139           localuser and localpass
140
141       ·   To the remote server with a user name and password of remoteuser
142           and remotepass
143
144       To set up the login paths in the .mylogin.cnf file, use the following
145       set commands. Enter each command on a single line, and enter the
146       appropriate passwords when prompted:
147
148           shell> mysql_config_editor set --login-path=client
149                    --host=localhost --user=localuser --password
150           Enter password: enter password "localpass" here
151           shell> mysql_config_editor set --login-path=remote
152                    --host=remote.example.com --user=remoteuser --password
153           Enter password: enter password "remotepass" here
154
155       mysql_config_editor uses the client login path by default, so the
156       --login-path=client option can be omitted from the first command
157       without changing its effect.
158
159       To see what mysql_config_editor writes to the .mylogin.cnf file, use
160       the print command:
161
162           shell> mysql_config_editor print --all
163           [client]
164           user = localuser
165           password = *****
166           host = localhost
167           [remote]
168           user = remoteuser
169           password = *****
170           host = remote.example.com
171
172       The print command displays each login path as a set of lines beginning
173       with a group header indicating the login path name in square brackets,
174       followed by the option values for the login path. Password values are
175       masked and do not appear as cleartext.
176
177       If you do not specify --all to display all login paths or
178       --login-path=name to display a named login path, the print command
179       displays the client login path by default, if there is one.
180
181       As shown by the preceding example, the login path file can contain
182       multiple login paths. In this way, mysql_config_editor makes it easy to
183       set up multiple “personalities” for connecting to different MySQL
184       servers, or for connecting to a given server using different accounts.
185       Any of these can be selected by name later using the --login-path
186       option when you invoke a client program. For example, to connect to the
187       remote server, use this command:
188
189           shell> mysql --login-path=remote
190
191       Here, mysql reads the [client] and [mysql] option groups from other
192       option files, and the [client], [mysql], and [remote] groups from the
193       login path file.
194
195       To connect to the local server, use this command:
196
197           shell> mysql --login-path=client
198
199       Because mysql reads the client and mysql login paths by default, the
200       --login-path option does not add anything in this case. That command is
201       equivalent to this one:
202
203           shell> mysql
204
205       Options read from the login path file take precedence over options read
206       from other option files. Options read from login path groups appearing
207       later in the login path file take precedence over options read from
208       groups appearing earlier in the file.
209
210       mysql_config_editor adds login paths to the login path file in the
211       order you create them, so you should create more general login paths
212       first and more specific paths later. If you need to move a login path
213       within the file, you can remove it, then recreate it to add it to the
214       end. For example, a client login path is more general because it is
215       read by all client programs, whereas a mysqldump login path is read
216       only by mysqldump. Options specified later override options specified
217       earlier, so putting the login paths in the order client, mysqldump
218       enables mysqldump-specific options to override client options.
219
220       When you use the set command with mysql_config_editor to create a login
221       path, you need not specify all possible option values (host name, user
222       name, password, port, socket). Only those values given are written to
223       the path. Any missing values required later can be specified when you
224       invoke a client path to connect to the MySQL server, either in other
225       option files or on the command line. Any options specified on the
226       command line override those specified in the login path file or other
227       option files. For example, if the credentials in the remote login path
228       also apply for the host remote2.example.com, connect to the server on
229       that host like this:
230
231           shell> mysql --login-path=remote --host=remote2.example.com
232
233       mysql_config_editor General Options
234
235       mysql_config_editor supports the following general options, which may
236       be used preceding any command named on the command line. For
237       descriptions of command-specific options, see mysql_config_editor
238       Commands and Command-Specific Options.
239
240       ·   --help, -?  Display a general help message and exit.
241
242           To see a command-specific help message, invoke mysql_config_editor
243           as follows, where command is a command other than help:
244
245               shell> mysql_config_editor command --help
246
247       ·   --debug[=debug_options], -# debug_options Write a debugging log. A
248           typical debug_options string is d:t:o,file_name. The default is
249           d:t:o,/tmp/mysql_config_editor.trace.
250
251           This option is available only if MySQL was built using WITH_DEBUG.
252           MySQL release binaries provided by Oracle are not built using this
253           option.
254
255       ·   --verbose, -v Verbose mode. Print more information about what the
256           program does. This option may be helpful in diagnosing problems if
257           an operation does not have the effect you expect.
258
259       ·   --version, -V Display version information and exit.
260       mysql_config_editor Commands and Command-Specific Options
261
262       This section describes the permitted mysql_config_editor commands, and,
263       for each one, the command-specific options permitted following the
264       command name on the command line.
265
266       In addition, mysql_config_editor supports general options that can be
267       used preceding any command. For descriptions of these options, see
268       mysql_config_editor General Options.
269
270       mysql_config_editor supports these commands:
271
272       ·   help
273
274           Display a general help message and exit. This command takes no
275           following options.
276
277           To see a command-specific help message, invoke mysql_config_editor
278           as follows, where command is a command other than help:
279
280               shell> mysql_config_editor command --help
281
282       ·   print [options]
283
284           Print the contents of the login path file in unobfuscated form,
285           with the exception that passwords are displayed as *****.
286
287           The default login path name is client if no login path is named. If
288           both --all and --login-path are given, --all takes precedence.
289
290           The print command permits these options following the command name:
291
292           ·   --help, -?
293
294               Display a help message for the print command and exit.
295
296               To see a general help message, use mysql_config_editor --help.
297
298           ·   --all
299
300               Print the contents of all login paths in the login path file.
301
302           ·   --login-path=name, -G name
303
304               Print the contents of the named login path.
305
306       ·   remove [options]
307
308           Remove a login path from the login path file, or modify a login
309           path by removing options from it.
310
311           This command removes from the login path only such options as are
312           specified with the --host, --password, --port, --socket, and --user
313           options. If none of those options are given, remove removes the
314           entire login path. For example, this command removes only the user
315           option from the mypath login path rather than the entire mypath
316           login path:
317
318               shell> mysql_config_editor remove --login-path=mypath --user
319
320           This command removes the entire mypath login path:
321
322               shell> mysql_config_editor remove --login-path=mypath
323
324           The remove command permits these options following the command
325           name:
326
327           ·   --help, -?
328
329               Display a help message for the remove command and exit.
330
331               To see a general help message, use mysql_config_editor --help.
332
333           ·   --host, -h
334
335               Remove the host name from the login path.
336
337           ·   --login-path=name, -G name
338
339               The login path to remove or modify. The default login path name
340               is client if this option is not given.
341
342           ·   --password, -p
343
344               Remove the password from the login path.
345
346           ·   --port, -P
347
348               Remove the TCP/IP port number from the login path.
349
350           ·   --socket, -S
351
352               Remove the Unix socket file name from the login path.
353
354           ·   --user, -u
355
356               Remove the user name from the login path.
357
358           ·   --warn, -w
359
360               Warn and prompt the user for confirmation if the command
361               attempts to remove the default login path (client) and
362               --login-path=client was not specified. This option is enabled
363               by default; use --skip-warn to disable it.
364
365       ·   reset [options]
366
367           Empty the contents of the login path file.
368
369           The reset command permits these options following the command name:
370
371           ·   --help, -?
372
373               Display a help message for the reset command and exit.
374
375               To see a general help message, use mysql_config_editor --help.
376
377       ·   set [options]
378
379           Write a login path to the login path file.
380
381           This command writes to the login path only such options as are
382           specified with the --host, --password, --port, --socket, and --user
383           options. If none of those options are given, mysql_config_editor
384           writes the login path as an empty group.
385
386           The set command permits these options following the command name:
387
388           ·   --help, -?
389
390               Display a help message for the set command and exit.
391
392               To see a general help message, use mysql_config_editor --help.
393
394           ·   --host=host_name, -h host_name
395
396               The host name to write to the login path.
397
398           ·   --login-path=name, -G name
399
400               The login path to create. The default login path name is client
401               if this option is not given.
402
403           ·   --password, -p
404
405               Prompt for a password to write to the login path. After
406               mysql_config_editor displays the prompt, type the password and
407               press Enter. To prevent other users from seeing the password,
408               mysql_config_editor does not echo it.
409
410               To specify an empty password, press Enter at the password
411               prompt. The resulting login path written to the login path file
412               includes a line like this:
413
414                   password =
415
416           ·   --port=port_num, -P port_num
417
418               The TCP/IP port number to write to the login path.
419
420           ·   --socket=file_name, -S file_name
421
422               The Unix socket file name to write to the login path.
423
424           ·   --user=user_name, -u user_name
425
426               The user name to write to the login path.
427
428           ·   --warn, -w
429
430               Warn and prompt the user for confirmation if the command
431               attempts to overwrite an existing login path. This option is
432               enabled by default; use --skip-warn to disable it.
433
435       Copyright © 1997, 2020, Oracle and/or its affiliates.
436
437       This documentation is free software; you can redistribute it and/or
438       modify it only under the terms of the GNU General Public License as
439       published by the Free Software Foundation; version 2 of the License.
440
441       This documentation is distributed in the hope that it will be useful,
442       but WITHOUT ANY WARRANTY; without even the implied warranty of
443       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
444       General Public License for more details.
445
446       You should have received a copy of the GNU General Public License along
447       with the program; if not, write to the Free Software Foundation, Inc.,
448       51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA or see
449       http://www.gnu.org/licenses/.
450
451

SEE ALSO

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

AUTHOR

458       Oracle Corporation (http://dev.mysql.com/).
459
460
461
462MySQL 8.0                         11/26/2020            MYSQL_CONFIG_EDITOR(1)
Impressum