merge

@item

Help for all commands from the client.

@item

Secure connections (with SSL).

@item

@code{SHOW COLUMNS FROM table_name} (used by @code{mysql} client to allow

expansions of column names) should not open the table, but only the

definition file. This will require less memory and be much faster.

@code{ulimit -c 1000000} to @code{safe_mysqld} or starting @code{safe_mysqld}

with @code{--core-file-sizes=1000000}. @xref{safe_mysqld, , @code{safe_mysqld}}.

To get a core dump on Linux if @code{mysqld} dies with a SIGSEGV signal, you can 

start @code{mysqld} with the @code{--core-file} option.  Note that you also probably

need to raise the @code{core file size} by adding @code{ulimit -c 1000000} to

@code{safe_mysqld} or starting @code{safe_mysqld} with 

@code{--core-file-sizes=1000000}.  @xref{safe_mysqld, , @code{safe_mysqld}}.

To get a core dump on Linux if @code{mysqld} dies with a SIGSEGV signal,

you can start @code{mysqld} with the @code{--core-file} option.  Note

that you also probably need to raise the @code{core file size} by adding

@code{ulimit -c 1000000} to @code{safe_mysqld} or starting

@code{safe_mysqld} with @code{--core-file-sizes=1000000}.

@xref{safe_mysqld, , @code{safe_mysqld}}.

If you are linking your own MySQL client and get the error:

@cindex options, command-line

@cindex mysqld options

In most cases you should manage mysqld options through option files.

@xref{Option files}.

@code{mysqld} and @code{mysqld.server} reads options from the

@code{mysqld} and @code{server} groups. @code{mysqld_safe} read options

from the @code{mysqld}, @code{server}, @code{mysqld_safe} and

@code{safe_mysqld} groups.  An embedded MySQL server usually reads

options from the @code{server}, @code{embedded} and

@code{xxxxx_SERVER}, where @code{xxxxx} is the name of the application.

@code{mysqld} accepts the following command-line options:

@table @code

environment variable values. @xref{Environment variables}.

The following programs support option files:  @code{mysql},

@code{mysqladmin}, @code{mysqld}, @code{mysqldump}, @code{mysqlimport},

@code{mysql.server}, @code{myisamchk}, and @code{myisampack}.

@code{mysqladmin}, @code{mysqld}, @code{mysqld_safe}, @code{mysql.server},

@code{mysqldump}, @code{mysqlimport}, @code{mysqlshow}, @code{mysqlcheck},

@code{myisamchk}, and @code{myisampack}.

You can use option files to specify any long option that a program supports!

Run the program with @code{--help} to get a list of available options.

@uref{http://www.ssh.com}.  With this, you can get an encrypted TCP/IP 

connection between a MySQL server and a MySQL client.

If you are using MySQL 4.0, you can also use internal openssl support.

@xref{Secure connections}.

To make a MySQL system secure, you should strongly consider the

following suggestions:

* Adding users::                Adding New Users to MySQL

* Passwords::                   Setting Up Passwords

* Password security::           Keeping Your Password Secure

* Secure connections::          Using Secure Connections

@end menu

MySQL grant tables.

@end itemize

-----------

@cindex SSL and X509 Basics

MySQL has support for SSL encrypted connetions. To understand how MySQL uses 

SSL we need to explain some basics about SSL and X509. People who are already 

aware of it can skip this chapter.

By default, MySQL uses unencrypted connections between client and server. This means

that anyone on the way can listen and read all your data which moves there. Even

more, some people can change content of data while it is moving between client and

server. Sometime you may need to move really secret data over public networks and 

such publicity is unacceptable. 

SSL is a protocol which uses different encryption algorithms to ensure that data 

which comes from public network can be trusted. It have mechanisms to detect any

change, loss or replay of data. SSL also incorpores algorithms to recognize and 

verification of identity using X509 standard.

@cindex What is encryption

Encryption is the way to make any kind of data unreadable. Even more, today's 

practice require many additional security elements from encryption algorithms.

They should resist many kind of known attacks like just messing with order 

of encrypted messages or replaying data twice.

@cindex What is X509/Certificate?

X509 is standard which makes possible to identity someone in the Internet. Mostly

it is used in e-commerce over the Internet. Shortly speaking there should be some

company called "Certificate Authority" which assigns electronic certificates to

everyone who needs. Certificates rely on asymmetric encryption algorithms which

have two encryption keys - public and secret. Certificate owner can prove his

identity showing certificate to other party. Certificate consists his owner public

key. Any data encrypted with it can be decrypted only by secret key holder. 

@cindex Possible questions:

Q: Why MySQL not uses encrypted connections by default?

A: Because it makes MySQL slower. Any kind of additional functionality requires 

computer to do additional work and encrypting data is CPU-intensive operation which

can overcome MySQL own work and consumed time. MySQL is tuned to be fast by default.

Q: I need more information about SSL/X509/encrpytion/whatever

A: Use your favourite internet search engine and search for keywords you are interested in.

------------

@cindex SSL related options

MySQL can check x509 certificate attributes additionally to most used username/password 

cheme. All usual options are still required (username, password, IP address mask, database/table name).

There are different possibilities to limit connections:

@itemize @bullet

@item

Without any SSL/X509 options all kind of encrypted/unencrypted connections are allowed if

  username and password are valid.

@item

@code{REQUIRE SSL} option makes SSL encrypted connection must. Note that this requirement

can be omitted of there are any other ACL record which allows non-SSL connection.

Example:

@example

GRANT ALL PRIVILEGES ON test.* TO root@@localhost IDENTIFIED BY "goodsecret" REQUIRE SSL

@end example

For a description of using @code{REQUIRE}, see @xref{Secure connections}.

@item

* @code{REQUIRE X509} Requiring X509 certificate means that client should have valid certificate

but we do not care about exact certificate, issuer or subject. Only restriction is it should

be possible to verify its signature with some of our CA certificates.

Example:

@example

GRANT ALL PRIVILEGES ON test.* TO root@@localhost IDENTIFIED BY "goodsecret" REQUIRE X509

@end example

@item

@code{REQUIRE ISSUER issuer} makes connection more restrictive: now client must present

  valid x509 certificate issued by CA "issuer". Using x509 certificates always implies encryption,

  so option "SSL" is not neccessary anymore.

Example:

@example

GRANT ALL PRIVILEGES ON test.* TO root@@localhost IDENTIFIED BY "goodsecret" REQUIRE ISSUER "C=FI, ST=Some-State, L=Helsinki, O=MySQL Finland AB, CN=Tonu Samuel/Email=tonu@@mysql.com"

@end example

@item

@code{REQUIRE SUBJECT subject} requires client to have valid x509 certificate with subject "subject" on it. If client have valid certificate but having different "subject" then connection is still

not allowed.

Example:

@example

GRANT ALL PRIVILEGES ON test.* TO root@@localhost IDENTIFIED BY "goodsecret" REQUIRE SUBJECT "C=EE, ST=Some-State, L=Tallinn, O=MySQL demo client certificate, CN=Tonu Samuel/Email=tonu@@mysql.com"

@end example

@item

@code{REQUIRE CIPHER cipher} is needed to assure enough strong ciphers and keylengths to be used. SSL himself can be weak if old algorithms with short encryption keys are used. Using this option we can ask for some exact cipher to allow connection.

Example:

@example

GRANT ALL PRIVILEGES ON test.* TO root@@localhost IDENTIFIED BY "goodsecret" REQUIRE CIPHER "EDH-RSA-DES-CBC3-SHA"

@end example

Also it is allowed to combine those options with each other like this:

@example

GRANT ALL PRIVILEGES ON test.* TO root@@localhost IDENTIFIED BY "goodsecret" 

	REQUIRE SUBJECT "C=EE, ST=Some-State, L=Tallinn, O=MySQL demo client certificate, CN=Tonu Samuel/Email=tonu@@mysql.com" 

	AND ISSUER "C=FI, ST=Some-State, L=Helsinki, O=MySQL Finland AB, CN=Tonu Samuel/Email=tonu@@mysql.com" 

	AND CIPHER "EDH-RSA-DES-CBC3-SHA"

@end example

But it is not allowed to use any of options twice. Only different options can be mixed.

@end itemize

-----------

@node User names, Privilege changes, GRANT, User Account Management

@subsection MySQL User Names and Passwords

Unix password file. @xref{User names}.

@node Password security,  , Passwords, User Account Management

@node Password security, Secure connections, Passwords, User Account Management

@subsection Keeping Your Password Secure

It is inadvisable to specify your password in a way that exposes it to

password or to specify the password in a properly protected @file{.my.cnf}

file.

@node Secure connections,  , Password security, User Account Management

@subsection Using Secure Connections

@cindex openssl

@cindex SSL and X509 Basics

@menu

* Secure basics::               Basics

* Secure requirements::         Requirements

* Secure GRANT::                GRANT OPTIONS

@end menu

@node Secure basics, Secure requirements, Secure connections, Secure connections

@subsubsection Basics

MySQL has support for SSL encrypted connetions. To understand how MySQL

uses SSL we need to explain some basics about SSL and X509. People who

are already aware of it can skip this chapter.

By default, MySQL uses unencrypted connections between client and

server. This means that anyone on the way can listen and read all your

data which moves there. Even more, some people can change content of

data while it is moving between client and server. Sometime you may need

to move really secret data over public networks and such publicity is

unacceptable.

SSL is a protocol which uses different encryption algorithms to ensure

that data which comes from public network can be trusted. It have

mechanisms to detect any change, loss or replay of data. SSL also

incorpores algorithms to recognize and verification of identity using

X509 standard.

@cindex What is encryption

Encryption is the way to make any kind of data unreadable. Even more,

today's practice require many additional security elements from

encryption algorithms.  They should resist many kind of known attacks

like just messing with order of encrypted messages or replaying data

twice.

@cindex What is X509/Certificate?

X509 is standard which makes possible to identity someone in the

Internet. Mostly it is used in e-commerce over the Internet. Shortly

speaking there should be some company called "Certificate Authority"

which assigns electronic certificates to everyone who

needs. Certificates rely on asymmetric encryption algorithms which have

two encryption keys - public and secret. Certificate owner can prove his

identity showing certificate to other party. Certificate consists his

owner public key. Any data encrypted with it can be decrypted only by

secret key holder.

@cindex Possible questions:

MySQL doesn't use encrypted on connections by default because this would

make the client/server protocol much slower. Any kind of additional

functionality requires computer to do additional work and encrypting

data is CPU-intensive operation which can overcome MySQL own work and

consumed time. By default MySQL is tuned to be fast as possible.

If you need more information about SSL/X509/encryption, you should use

your favourite internet search engine and search for keywords you are

interested in.

@node Secure requirements, Secure GRANT, Secure basics, Secure connections

@subsubsection Requirements

To get secure connections to work with MySQL you must do the following:

@enumerate

@item

Install the openssh library. We have tested MySQL with openssl 0.9.6.

@uref{http://www.openssh.org}.

@item

Configure MySQL with @code{--with-vio --with-openssl}.

@item

If you are using an old MySQL installation, you have to update your

@code{mysql.user} table with some new columns. You can do this by

running the @code{mysql_fix_privilege_tables.sh} script.

@item

You can check if a running mysqld server supports @code{openssl} by

examining if @code{show variables like 'have_openssl'} returns @code{YES}.

@end enumerate

@node Secure GRANT,  , Secure requirements, Secure connections

@subsubsection GRANT options

@cindex SSL related options

@findex REQUIRE GRANT option

@findex GRANT statemenet

MySQL can check x509 certificate attributes additionally to most used

username/password cheme. All usual options are still required (username,

password, IP address mask, database/table name).

There are different possibilities to limit connections:

@itemize @bullet

@item

Without any SSL/X509 options all kind of encrypted/unencrypted

connections are allowed if username and password are valid.

@item

@code{REQUIRE SSL} option makes SSL encrypted connection must. Note that

this requirement can be omitted of there are any other ACL record which

allows non-SSL connection.

@example

GRANT ALL PRIVILEGES ON test.* TO root@@localhost IDENTIFIED BY

"goodsecret" REQUIRE SSL

@end example

@item

@code{REQUIRE X509} Requiring X509 certificate means that client

should have valid certificate but we do not care about exact

certificate, issuer or subject. Only restriction is it should be

possible to verify its signature with some of our CA certificates.

@example

GRANT ALL PRIVILEGES ON test.* TO root@@localhost IDENTIFIED BY "goodsecret" REQUIRE X509

@end example

@item

@code{REQUIRE ISSUER issuer} makes connection more restrictive: now

client must present valid x509 certificate issued by CA "issuer". Using

x509 certificates always implies encryption, so option "SSL" is not

neccessary anymore.

@example

GRANT ALL PRIVILEGES ON test.* TO root@@localhost IDENTIFIED BY "goodsecret" REQUIRE ISSUER "C=FI, ST=Some-State, L=Helsinki, O=MySQL Finland AB, CN=Tonu Samuel/Email=tonu@@mysql.com"

@end example

@item

@code{REQUIRE SUBJECT subject} requires client to have valid x509

certificate with subject "subject" on it. If client have valid

certificate but having different "subject" then connection is still not

allowed.

@example

GRANT ALL PRIVILEGES ON test.* TO root@@localhost IDENTIFIED BY "goodsecret" REQUIRE SUBJECT "C=EE, ST=Some-State, L=Tallinn, O=MySQL demo client certificate, CN=Tonu Samuel/Email=tonu@@mysql.com"

@end example

@item

@code{REQUIRE CIPHER cipher} is needed to assure enough strong ciphers

and keylengths to be used. SSL himself can be weak if old algorithms

with short encryption keys are used. Using this option we can ask for

some exact cipher to allow connection.

@example

GRANT ALL PRIVILEGES ON test.* TO root@@localhost IDENTIFIED BY "goodsecret" REQUIRE CIPHER "EDH-RSA-DES-CBC3-SHA"

@end example

Also it is allowed to combine those options with each other like this:

@example

GRANT ALL PRIVILEGES ON test.* TO root@@localhost IDENTIFIED BY "goodsecret" 

REQUIRE SUBJECT "C=EE, ST=Some-State, L=Tallinn, O=MySQL demo client certificate, CN=Tonu Samuel/Email=tonu@@mysql.com" 

AND ISSUER "C=FI, ST=Some-State, L=Helsinki, O=MySQL Finland AB, CN=Tonu Samuel/Email=tonu@@mysql.com" 

AND CIPHER "EDH-RSA-DES-CBC3-SHA"

@end example

But it is not allowed to use any of options twice. Only different

options can be mixed.

@end itemize

@node Disaster Prevention, Database Administration, User Account Management, MySQL Database Administration

@section Disaster Prevention and Recovery

The supported character sets.

@item @code{concurrent_inserts}

If @code{ON} (the default), MySQL will allow you to use @code{INSERT}

on @code{MyISAM} tables at the same time as you run @code{SELECT} queries

on them.  You can turn this option off by starting @code{mysqld} with @code{--safe}

or @code{--skip-new}.

If @code{ON} (the default), MySQL will allow you to use @code{INSERT} on

@code{MyISAM} tables at the same time as you run @code{SELECT} queries

on them.  You can turn this option off by starting @code{mysqld} with

@code{--safe} or @code{--skip-new}.

@cindex timeout

@item @code{connect_timeout}

* C API function overview::     C API Function Overview

* C API functions::             C API Function Descriptions

* C Thread functions::          C Thread Functions

* C Embedded Server functions:: C Embedded Server Functions

* C Embedded Server func::      C Embedded Server Function Descriptions

* C API problems::              Common questions and problems when using the C API

* Building clients::            Building Client Programs

* Threaded clients::            How to Make a Threaded Client

An unknown error occurred.

@end table

@node C Thread functions, C Embedded Server functions, C API functions, C

@node C Thread functions, C Embedded Server func, C API functions, C

@subsection C Threaded Function Descriptions

You need to use the following functions when you want to create a

none.

@node C Embedded Server functions, C API problems, C Thread functions, C

@node C Embedded Server func, C API problems, C Thread functions, C

@subsection C Embedded Server Function Descriptions

You must use the following functions if you want to allow your

* mysql_server_end()::          

@end menu

@node mysql_server_init(), mysql_server_end(), C Embedded Server functions, C Embedded Server functions

@node mysql_server_init(), mysql_server_end(), C Embedded Server func, C Embedded Server func

@subsubsection @code{mysql_server_init()}

@findex @code{mysql_server_init()}

@code{void mysql_server_init(int argc, const char **argv, const char **groups)}

@code{int mysql_server_init(int argc, const char **argv, const char **groups)}

@subsubheading Description

calling any other MySQL function.  It starts up the server and

initializes any subsystems (@code{mysys}, InnoDB, etc.) that the

server uses.  If this function is not called, the program will

crash.

crash.  If you are using the DBUG package that comes with MySQL,

you should call this after you have called @code{MY_INIT()}.

The @code{argc} and @code{argv} arguments are analogous to the

arguments to @code{main()}.  The first element of @code{argv}

@subsubheading Return Values

none.

0 if ok, 1 if an error occurred.

@node mysql_server_end(),  , mysql_server_init(), C Embedded Server functions

@node mysql_server_end(),  , mysql_server_init(), C Embedded Server func

@subsubsection @code{mysql_server_end()}

@findex @code{mysql_server_end()}

none.

@node C API problems, Building clients, C Embedded Server functions, C

@node C API problems, Building clients, C Embedded Server func, C

@subsection Common questions and problems when using the C API

@tindex @code{mysql_query()}

from mysql_com.h, and added @code{mysql_thread_init()} and

@code{mysql_thread_end()} to mysql.h.

@item

Secure connections (with SSL).

@item

Unsigned @code{BIGINT} constants now work. @code{MIN()} and @code{MAX()}

now handles signed and unsigned @code{BIGINT} numbers correctly.

@item

};

static const char *load_default_groups[]= { "mysql","client",0 };

static const char *server_default_groups[]= { "server", "mysql_SERVER", 0 };

static const char *server_default_groups[]=

{ "server", "embedded", "mysql_SERVER", 0 };

#ifdef HAVE_READLINE

extern "C" void add_history(char *command); /* From readline directory */

{

  char buff[80];

  mysql_server_init(0, NULL, server_default_groups);

  MY_INIT(argv[0]);

  DBUG_ENTER("main");

  DBUG_PROCESS(argv[0]);

      !(status.line_buff=batch_readline_init(max_allowed_packet+512,stdin)))

    exit(1);

  glob_buffer.realloc(512);

  mysql_server_init(0, NULL, server_default_groups);

  completion_hash_init(&ht,50);

  bzero((char*) &mysql, sizeof(mysql));

  if (sql_connect(current_host,current_db,current_user,opt_password,

  if (opt_outfile)

    end_tee();

  mysql_end(0);

  mysql_server_end();

#ifndef _lint

  DBUG_RETURN(0);				// Keep compiler happy

#endif

  my_free(current_db,MYF(MY_ALLOW_ZERO_PTR));

  my_free(current_host,MYF(MY_ALLOW_ZERO_PTR));

  my_free(current_user,MYF(MY_ALLOW_ZERO_PTR));

  mysql_server_end();

  my_end(info_flag ? MY_CHECK_ERROR | MY_GIVE_INFO : 0);

  exit(status.exit_status);

}

static void close_files()

{

  do

  DBUG_ENTER("close_files");

  for (; cur_file != file_stack ; cur_file--)

  {

    if (*cur_file != stdin && *cur_file)

      my_fclose(*cur_file,MYF(0));

  } while (cur_file-- != file_stack);

  }

  DBUG_VOID_RETURN;

}

static void free_used_memory()

{

  uint i;

  DBUG_ENTER("free_used_memory");

  close_cons();

  close_files();

  hash_free(&var_hash);

  dynstr_free(&ds_res);

  my_free(pass,MYF(MY_ALLOW_ZERO_PTR));

  free_defaults(default_argv);

  mysql_server_end();

  my_end(MY_CHECK_ERROR);

  DBUG_VOID_RETURN;

}

static void die(const char* fmt, ...)

    {

      if ((*cur_file) != stdin)

	my_fclose(*cur_file,MYF(0));

      if (cur_file == file_stack)

	return 1;

      else

      {

      cur_file--;

      lineno--;

      if (cur_file == file_stack)

	return 1;

      continue;

    }

    }

    switch(state) {

    case R_NORMAL:

	result_file = optarg;

	break;

      case 'x':

      if (!(*cur_file = my_fopen(optarg, O_RDONLY, MYF(MY_WME))))

      if (!(*++cur_file = my_fopen(optarg, O_RDONLY, MYF(MY_WME))))

	  die("Could not open %s: errno = %d", optarg, errno);

	break;

      case 'p':

  struct st_query* q;

  my_bool require_file=0, q_send_flag=0;

  char save_file[FN_REFLEN];

  mysql_server_init(sizeof(embedded_server_args) / sizeof(char *) - 1,

		    embedded_server_args, embedded_server_groups);

  MY_INIT(argv[0]);

  {

  DBUG_ENTER("main");

  DBUG_PROCESS(argv[0]);

  save_file[0]=0;

  TMPDIR[0]=0;

  *block_ok = 1;

  init_dynamic_string(&ds_res, "", 0, 65536);

  parse_args(argc, argv);

  if (mysql_server_init(sizeof(embedded_server_args) / sizeof(char *) - 1,

			embedded_server_args, embedded_server_groups))

    die("Can't initialize MySQL server");

  init_var_hash();

  if (!*cur_file)

    *cur_file = stdin;

  if (cur_file == file_stack)

    *++cur_file = stdin;

  *lineno=1;

  if (!( mysql_init(&cur_con->mysql)))

      printf("ok\n");

  }

  mysql_server_end();

  free_used_memory();

  exit(error ? 1 : 0);

  return error ? 1 : 0;				/* Keep compiler happy */

  DBUG_RETURN(error ? 1 : 0);			/* Keep compiler happy */

  }

}

#define statistic_add(V,C,L)       (V)+=(C)

#endif

/* Macros to make switching between C and C++ mode easier */

#ifdef __cplusplus

#define C_MODE_START    extern "C" {

#define C_MODE_END	}

#else

#define C_MODE_START

#define C_MODE_END

#endif

#endif /* _global_h */

#define MY_WAIT_FOR_USER_TO_FIX_PANIC	60	/* in seconds */

#define MY_WAIT_GIVE_USER_A_MESSAGE	10	/* Every 10 times of prev */

#define MIN_COMPRESS_LENGTH		50	/* Don't compress small bl. */

#define KEYCACHE_BLOCK_SIZE		1024

#define DEFAULT_KEYCACHE_BLOCK_SIZE	1024

#define MAX_KEYCACHE_BLOCK_SIZE		16384

	/* root_alloc flags */

#define MY_KEEP_PREALLOC	1

extern ulong	_my_cache_w_requests,_my_cache_write,_my_cache_r_requests,

		_my_cache_read;

extern ulong	_my_blocks_used,_my_blocks_changed;

extern uint	key_cache_block_size;

extern ulong	my_file_opened,my_stream_opened, my_tmp_file_created;

extern my_bool	key_cache_inited;

extern my_bool	key_cache_inited, my_init_done;

					/* Point to current my_message() */

extern void (*my_sigtstp_cleanup)(void),

my_bool my_uncompress(byte *, ulong *, ulong *);

byte *my_compress_alloc(const byte *packet, ulong *len, ulong *complen);

ulong checksum(const byte *mem, uint count);

uint my_bit_log2(ulong value);

#if defined(_MSC_VER) && !defined(__WIN__)

extern void sleep(int sec);