AppSuite:Oxsysreport: Difference between revisions
No edit summary |
No edit summary |
||
| Line 6: | Line 6: | ||
<div class="title">Creating an OX Support Tarball</div> | <div class="title">Creating an OX Support Tarball</div> | ||
The | The <code>/opt/open-xchange/sbin/oxsysreport</code> tool will collect a lot of useful log and system information into a tar archive. This so called OX Support Tarball contains Apache and OX configurations, OX logs and system information. This and a qualified error report makes sure that our support department get all needed details for fast effective help. We always recommend to encrypt your e-mail with our [http://software.open-xchange.com/0x51E6AA1C-oxsupportkey.pub Support Key] when attaching this tarball. | ||
__TOC__ | __TOC__ | ||
| Line 18: | Line 18: | ||
| Required Tools | | Required Tools | ||
|- | |- | ||
| --tempdir | | <code>--tempdir</code> | ||
| /tmp | | <code>/tmp</code> | ||
| <path> | | <code><path></code> | ||
| | | | ||
| | | | ||
|- | |- | ||
| --logdir | | <code>--logdir</code> | ||
| ox_support_infos-<timestamp> | | <code>ox_support_infos-<timestamp></code> | ||
| <folder name> | | <code><folder name></code> | ||
| | | | ||
|- | |- | ||
| --log-archive | | <code>--log-archive</code> | ||
| /tmp/ox_support_infos-<timestamp>.tar.gz | | <code>/tmp/ox_support_infos-<timestamp>.tar.gz</code> | ||
| <path to tarball> | | <code><path to tarball></code> | ||
| | | | ||
|- | |- | ||
| --keep-tmp-files | | <code>--keep-tmp-files</code> | ||
| false | | <code>false</code> | ||
| true false | | <code>true false</code> | ||
| | | | ||
|- | |- | ||
| --thread-dump | | <code>--thread-dump</code> | ||
| false | | <code>false</code> | ||
| true false | | <code>true false</code> | ||
| | | | ||
|- | |- | ||
| --heap-dump | | <code>--heap-dump</code> | ||
| false | | <code>false</code> | ||
| true false | | <code>true false</code> | ||
| jmap, sudo (Only if not IBM Java) | | jmap, sudo (Only if not IBM Java) | ||
|- | |- | ||
| --skip-compression | | <code>--skip-compression</code> | ||
| false | | <code>false</code> | ||
| true false | | <code>true false</code> | ||
| | | | ||
|- | |- | ||
| --exclude-old-logs | | <code>--exclude-old-logs</code> | ||
| disabled | | <code>disabled</code> | ||
| 0 ... n Days | | <code>0 ... n</code> Days | ||
| | | | ||
|- | |- | ||
| --exclude-ox-secrets | | <code>--exclude-ox-secrets</code> | ||
| false | | <code>false</code> | ||
| true false | | <code>true false</code> | ||
| | | | ||
|- | |- | ||
| -h,--help | | <code>-h,--help</code> | ||
| disabled | | <code>disabled</code> | ||
| | | | ||
| | | | ||
| Line 107: | Line 107: | ||
= Features = | = Features = | ||
== Directory for Temporary Process Data (--tempdir) == | == Directory for Temporary Process Data (<code>--tempdir</code>) == | ||
If you need by e.g. space limitations to switch to a different drive for collecting and processing the data, you can choose here an alternative but existing path. | If you need by e.g. space limitations to switch to a different drive for collecting and processing the data, you can choose here an alternative but existing path. | ||
== Output Log Directory Name (--logdir) == | == Output Log Directory Name (<code>--logdir</code>) == | ||
We do not recommend to use this option, but you can choose the output log directory name of the data collection and processing. This will also be the root folder of the OX Support Tarball. Please note, this tempory folder will be removed by default and you need to choose an not existing directory name. | We do not recommend to use this option, but you can choose the output log directory name of the data collection and processing. This will also be the root folder of the OX Support Tarball. Please note, this tempory folder will be removed by default and you need to choose an not existing directory name. | ||
== OX Support Tarball Name and Storage Location (--log-archive) == | == OX Support Tarball Name and Storage Location (<code>--log-archive</code>) == | ||
By this you can choose an alternative tarball name and storage location. Please note, the script will check and break on already existing file arguments. | By this you can choose an alternative tarball name and storage location. Please note, the script will check and break on already existing file arguments. | ||
== Keep Temporary Process Data (--keep-tmp-files) == | == Keep Temporary Process Data (<code>--keep-tmp-files</code>) == | ||
If you like to observe the data collection without unpacking the tarball or to add additional files for repacking, feel free to use this option. The path to this directory will be shown by running this tool and is | If you like to observe the data collection without unpacking the tarball or to add additional files for repacking, feel free to use this option. The path to this directory will be shown by running this tool and is | ||
defined by /<--tempdir>/<--logdir>. | defined by <code>/<--tempdir>/<--logdir></code>. | ||
{{VersionFrom|7.6.0}} | {{VersionFrom|7.6.0}} | ||
== Create Thread Dumps (--thread-dump) == | == Create Thread Dumps (<code>--thread-dump</code>) == | ||
This option normaly should only be used in case it is requested by our Support department. The collected thread dumps may help to identify the root cause of long running threads, critical load und very high cpu usage incidents. In case of a very high cpu incident, please keep by the lack of resources the additional usage of | This option normaly should only be used in case it is requested by our Support department. The collected thread dumps may help to identify the root cause of long running threads, critical load und very high cpu usage incidents. In case of a very high cpu incident, please keep by the lack of resources the additional usage of <code>--skip-compression</code> in mind. | ||
=== Further Details of Thread Dump Creation === | === Further Details of Thread Dump Creation === | ||
This option triggers via 'kill -3' the thread dump creation and logs the related top output into the '/commands/top -d 3 -bHn 5 (thread-dump)' file. The thread dump on none IBM Java systems will are stored within the | This option triggers via '<code>kill -3</code>' the thread dump creation and logs the related top output into the '<code>/commands/top -d 3 -bHn 5 (thread-dump)</code>' file. The thread dump on none IBM Java systems will are stored within the <code>/var/log/open-xchange/open-xchange-console.log</code>, on IBM Java they will be stored separately inside the support tarball as <code>/tmp/javacore.<timestamp>.txt</code>. | ||
{{VersionFrom|7.6.0}} | {{VersionFrom|7.6.0}} | ||
== Create Heap Dumps (--heap-dump) == | == Create Heap Dumps (<code>--heap-dump</code>) == | ||
This option normaly should only be used in case it is requested by our Support department. The collected heap dumps could be very helpful in memory or OX service outage incidents. Please keep in mind that, you have to call oxsysreport with this option before restarting the service. | This option normaly should only be used in case it is requested by our Support department. The collected heap dumps could be very helpful in memory or OX service outage incidents. Please keep in mind that, you have to call <code>oxsysreport</code> with this option before restarting the service. | ||
First you will get an warning dialog with some system details and with the choice to proceed or to cancel. While creating Java heap dumps your JVM will be stopped and the OX Service is not functional. This step may | First you will get an warning dialog with some system details and with the choice to proceed or to cancel. While creating Java heap dumps your JVM will be stopped and the OX Service is not functional. This step may | ||
take several minutes and it could happen that you need to restart the open-xchange service afterwards manually again. | take several minutes and it could happen that you need to restart the <code>open-xchange</code> service afterwards manually again. | ||
You also have to make sure that you have enough free disk space for processing the data in directories which are defined by | You also have to make sure that you have enough free disk space for processing the data in directories which are defined by <code>--tempdir</code> and <code>--log-archive</code>. Depending on your max heap size '<code>-Xmx</code>' defined by your <code>ox-scriptconf.sh</code> of your groupware Java Virtual Machine and amount of logs, several gigabyte could be needed! | ||
=== Further Details of Heap Dump Creation === | === Further Details of Heap Dump Creation === | ||
This option triggers the creation of an heap dump which will be stored on none IBM Java Systems within '/commands/jmap -dump:file (heap-dump).bz2' and '/commands/jmap -histo (heap-dump)'. The two jmap files beside without '(heap-dump)' marker contain the stdout/stderr of jmap by running this command. Please note, the '.bz2' suffix (and compression) will be vanished by | This option triggers the creation of an heap dump which will be stored on none IBM Java Systems within '<code>/commands/jmap -dump:file (heap-dump).bz2</code>' and '<code>/commands/jmap -histo (heap-dump)</code>'. The two jmap files beside without '<code>(heap-dump)</code>' marker contain the <code>stdout/stderr</code> of jmap by running this command. Please note, the '<code>.bz2</code>' suffix (and compression) will be vanished by <code>--skip-compression</code> option. | ||
On IBM Java Systems the | On IBM Java Systems the <code>jmap</code> command is not available and '<code>kill -ABRT</code>' will do the job instead. This will kill the JVM completely by writing the heap dump, afterwards the dump will be moved within the tarball and processed by the tool <code>jextract</code>. Depending on <code>--skip-compression</code> option jextract will compress it as zip or not. The heap dump will be located <code>/tmp/core.<timestamp>.dmp.zip</code> within the tarball. The <code>stdout/stderr</code> of jextract will be written to '<code>/commands/jextract core.<timestamp>.dmp (heap-dump)</code>'. On IBM Java the OX groupware service will be restarted by this script . | ||
{{VersionFrom|7.6.0}} | {{VersionFrom|7.6.0}} | ||
== Skip Support Tarball Compression (--skip-compression) == | == Skip Support Tarball Compression (<code>--skip-compression</code>) == | ||
Please use this option only in case your system is affected by very high cpu usage and the oxsysreport compression stuck by the lack of resources. If this option is set, no compression takes place and this will effect the OX Support Tarball, as well as nested tarballs and possible heap dumps. The resulting tarball can | Please use this option only in case your system is affected by very high cpu usage and the oxsysreport compression stuck by the lack of resources. If this option is set, no compression takes place and this will effect the OX Support Tarball, as well as nested tarballs and possible heap dumps. The resulting tarball can | ||
very huge and we recommend to keep the | very huge and we recommend to keep the <code>--exclude-old-logs</code> option mind to drop also potential outdated logs. Please compress this tarball always before handing over to our support department. | ||
{{VersionFrom|7.6.0}} | {{VersionFrom|7.6.0}} | ||
== Exclude old OX Logfiles from Support Tarball (--exclude-old-logs) == | == Exclude old OX Logfiles from Support Tarball (<code>--exclude-old-logs</code>) == | ||
We recommend to use this option if you are able to locate the periode of facing a specific issue or by handing over an follow up tarball. This option will exclude all separate files beyond the modified period which are stored on your system in | We recommend to use this option if you are able to locate the periode of facing a specific issue or by handing over an follow up tarball. This option will exclude all separate files beyond the modified period which are stored on your system in <code>/var/log/open-xchange</code> or <code>/var/log/univention</code>. This option does not effect mandatory files like e.g. <code>open-xchange-console.log</code>. If logs are dropped they are listed in the generated overview file <code>/modified-and-excluded-files.txt</code> of the tarball. | ||
{{VersionFrom|7.6.0}} | {{VersionFrom|7.6.0}} | ||
== Remove Confidential Details from OX Config Files (--exclude-ox-secrets) == | == Remove Confidential Details from OX Config Files (<code>--exclude-ox-secrets</code>) == | ||
This option removes all unexpected, as well as hole confidential known files from the | This option removes all unexpected, as well as hole confidential known files from the <code>/opt/open-xchange/etc/</code> copy of the support tarball. Also confidential information like passwords and keys will be replaced by an white and blacklist heuristic with an <code><REMOVED BY OXSYSREPORT></code> marker. The replacement works only on OX properties files and the <code>/modified-and-excluded-files.txt</code> file will contain the details of affected files. | ||
= Examples = | = Examples = | ||
| Line 157: | Line 157: | ||
== Default Usage == | == Default Usage == | ||
root@server# /opt/open-xchange/sbin/oxsysreport | <code>root@server# /opt/open-xchange/sbin/oxsysreport</code> | ||
Revision as of 10:23, 30 May 2014
The /opt/open-xchange/sbin/oxsysreport tool will collect a lot of useful log and system information into a tar archive. This so called OX Support Tarball contains Apache and OX configurations, OX logs and system information. This and a qualified error report makes sure that our support department get all needed details for fast effective help. We always recommend to encrypt your e-mail with our Support Key when attaching this tarball.
Parameter Overview
| Option | Default Values | Possible Values | Required Tools | |
--tempdir
|
/tmp
|
<path>
|
||
--logdir
|
ox_support_infos-<timestamp>
|
<folder name>
|
||
--log-archive
|
/tmp/ox_support_infos-<timestamp>.tar.gz
|
<path to tarball>
|
||
--keep-tmp-files
|
false
|
true false
|
||
--thread-dump
|
false
|
true false
|
||
--heap-dump
|
false
|
true false
|
jmap, sudo (Only if not IBM Java) | |
--skip-compression
|
false
|
true false
|
||
--exclude-old-logs
|
disabled
|
0 ... n Days
|
||
--exclude-ox-secrets
|
false
|
true false
|
||
-h,--help
|
disabled
|
Required Tools
We recommend to check if all required tools are installed before a incident happens. In case your are running IBM Java on e.g. SUSE Linux Enterprise, heap dumps will be created differently. Please note, we do not list package names which are usually get installed in a default installation.
| Tool | Debian | SuSE | Redhead | CentOS | Univention |
| bzip2 | bzip2 | ||||
| jmap | sun-java<version>-jdk openjdk-<version>-jdk | N/A | java-<version>-openjdk-devel | java-<version>-openjdk-devel | openjdk-<version>-jdk |
| sudo | sudo |
Features
Directory for Temporary Process Data (--tempdir)
If you need by e.g. space limitations to switch to a different drive for collecting and processing the data, you can choose here an alternative but existing path.
Output Log Directory Name (--logdir)
We do not recommend to use this option, but you can choose the output log directory name of the data collection and processing. This will also be the root folder of the OX Support Tarball. Please note, this tempory folder will be removed by default and you need to choose an not existing directory name.
OX Support Tarball Name and Storage Location (--log-archive)
By this you can choose an alternative tarball name and storage location. Please note, the script will check and break on already existing file arguments.
Keep Temporary Process Data (--keep-tmp-files)
If you like to observe the data collection without unpacking the tarball or to add additional files for repacking, feel free to use this option. The path to this directory will be shown by running this tool and is
defined by /<--tempdir>/<--logdir>.
Create Thread Dumps (--thread-dump)
This option normaly should only be used in case it is requested by our Support department. The collected thread dumps may help to identify the root cause of long running threads, critical load und very high cpu usage incidents. In case of a very high cpu incident, please keep by the lack of resources the additional usage of --skip-compression in mind.
Further Details of Thread Dump Creation
This option triggers via 'kill -3' the thread dump creation and logs the related top output into the '/commands/top -d 3 -bHn 5 (thread-dump)' file. The thread dump on none IBM Java systems will are stored within the /var/log/open-xchange/open-xchange-console.log, on IBM Java they will be stored separately inside the support tarball as /tmp/javacore.<timestamp>.txt.
Create Heap Dumps (--heap-dump)
This option normaly should only be used in case it is requested by our Support department. The collected heap dumps could be very helpful in memory or OX service outage incidents. Please keep in mind that, you have to call oxsysreport with this option before restarting the service.
First you will get an warning dialog with some system details and with the choice to proceed or to cancel. While creating Java heap dumps your JVM will be stopped and the OX Service is not functional. This step may
take several minutes and it could happen that you need to restart the open-xchange service afterwards manually again.
You also have to make sure that you have enough free disk space for processing the data in directories which are defined by --tempdir and --log-archive. Depending on your max heap size '-Xmx' defined by your ox-scriptconf.sh of your groupware Java Virtual Machine and amount of logs, several gigabyte could be needed!
Further Details of Heap Dump Creation
This option triggers the creation of an heap dump which will be stored on none IBM Java Systems within '/commands/jmap -dump:file (heap-dump).bz2' and '/commands/jmap -histo (heap-dump)'. The two jmap files beside without '(heap-dump)' marker contain the stdout/stderr of jmap by running this command. Please note, the '.bz2' suffix (and compression) will be vanished by --skip-compression option.
On IBM Java Systems the jmap command is not available and 'kill -ABRT' will do the job instead. This will kill the JVM completely by writing the heap dump, afterwards the dump will be moved within the tarball and processed by the tool jextract. Depending on --skip-compression option jextract will compress it as zip or not. The heap dump will be located /tmp/core.<timestamp>.dmp.zip within the tarball. The stdout/stderr of jextract will be written to '/commands/jextract core.<timestamp>.dmp (heap-dump)'. On IBM Java the OX groupware service will be restarted by this script .
Skip Support Tarball Compression (--skip-compression)
Please use this option only in case your system is affected by very high cpu usage and the oxsysreport compression stuck by the lack of resources. If this option is set, no compression takes place and this will effect the OX Support Tarball, as well as nested tarballs and possible heap dumps. The resulting tarball can
very huge and we recommend to keep the --exclude-old-logs option mind to drop also potential outdated logs. Please compress this tarball always before handing over to our support department.
Exclude old OX Logfiles from Support Tarball (--exclude-old-logs)
We recommend to use this option if you are able to locate the periode of facing a specific issue or by handing over an follow up tarball. This option will exclude all separate files beyond the modified period which are stored on your system in /var/log/open-xchange or /var/log/univention. This option does not effect mandatory files like e.g. open-xchange-console.log. If logs are dropped they are listed in the generated overview file /modified-and-excluded-files.txt of the tarball.
Remove Confidential Details from OX Config Files (--exclude-ox-secrets)
This option removes all unexpected, as well as hole confidential known files from the /opt/open-xchange/etc/ copy of the support tarball. Also confidential information like passwords and keys will be replaced by an white and blacklist heuristic with an <REMOVED BY OXSYSREPORT> marker. The replacement works only on OX properties files and the /modified-and-excluded-files.txt file will contain the details of affected files.
Examples
Default Usage
root@server# /opt/open-xchange/sbin/oxsysreport