diff --git a/Troubleshooting.md b/Troubleshooting.md new file mode 100644 index 0000000..d9c9250 --- /dev/null +++ b/Troubleshooting.md @@ -0,0 +1,61 @@ +If the AUDIT plugin fails to install error messages will be logged in the MySQL error log. Log file location can be queried in MySQL by running the following command: + + show global variables like 'log_error'; + +Check the error log for AUDIT plugin print outs to better understand what is happening during the install process. + +### Checksum Validation + +AUDIT plugin uses compiled offsets for accessing built-in MySQL data structures that are not exposed through a consistent API. The use of offsets is used for supporting multiple MySQL versions with a single binary distribution. The plugin will use the proper offsets according to the MySQL server version. To verify that the plugin is running on a MySQL version which we know and tested the offsets for, we've added a checksum verification on the mysqld binary. Thus, if a MySQL server distribution, which we haven't extracted the offsets and checksum for, is being used, the plugin will fail installation as the checksum of mysqld will not match a known checksum. Usually, the offsets between different MySQL distributions are the same for a specific version. Thus, it is possible to run the AUDIT plugin with the offsets of a specific MySQL server version without checksum verification. If checksum verification fails the log will contain an error of the form: + +> Audit Plugin: Couldn't find proper THD offsets for: MYSQL_VERSION + +In this case, you can try to disable the checksum verification. To disable checksum verification: add to the MySQL option file (my.cnf) at the [mysqld] section the option: + + audit_validate_checksum=OFF + +Then try installing the AUDIT plugin either via plugin-load configuration option (restart) or by issuing the INSTALL PLUGIN statement. + +When checksum validation is turned off, AUDIT plugin will still search for valid offsets according to the MySQL version and perform basic validation on the offsets. If you still see in the error log the message: + +> Audit Plugin: Couldn't find proper THD offsets for: MYSQL_VERSION + +This means that either offsets for the exact MySQL version being used are not included in the build or that the offsets included didn't pass basic validation as a different distribution is being used. At this stage we recommend extracting the offsets (see next section). + +### Offset Extraction + +AUDIT plugin supports setting the offsets via configuration. So if the offsets are not included with the build it is possible to extract the offsets and configure AUDIT plugin to use these offsets. + +If the MySQL distribution includes debug symbols (most builds from mysql.com include debug symbols) it is possible to extract the offsets using a simple script. + +Download the offset-extract.sh script from: https://github.com/mcafee/mysql-audit/blob/master/offset-extract/offset-extract.sh + +Note: GDB is required to use this script. + +Change the permission of the file to executable: + + chmod +x offset-extract.sh + +Then run the following: + + ./offset-extract.sh + +From the output you will need to use the number offsets later on. + +Sample output: + +~# ./offset-extract.sh /usr/sbin/mysqld +//offsets for: /usr/sbin/mysqld (5.1.41-community) +{"5.1.41-community","6ccf4357688d8e46bfcb4443966970b0", **6200, 6264, 3672, 3944, 88, 2048**}, + +Then add to the mysqld configuration file (usually /etc/my.cnf) the following under the [mysqld] section: + + audit_offsets= + +The offset section for example should look like this: + + audit_offsets=6200, 6264, 3672, 3944, 88, 2048 + +Then try installing the AUDIT plugin either via plugin-load configuration option (restart) or by issuing the INSTALL PLUGIN statement. + +