'\" t .\" Title: AMINERREMOTECONTROL .\" Author: Markus Wurzenberger .\" Generator: DocBook XSL Stylesheets vsnapshot .\" Date: 01/31/2021 .\" Manual: logdata-anomaly-miner User Manual .\" Source: logdata-anomaly-miner .\" Language: English .\" .TH "AMINERREMOTECONTROL" "1" "01/31/2021" "logdata-anomaly-miner" "logdata-anomaly-miner User Man" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .\" http://bugs.debian.org/507673 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" ----------------------------------------------------------------- .\" * set default formatting .\" ----------------------------------------------------------------- .\" disable hyphenation .nh .\" disable justification (adjust text to left margin only) .ad l .\" ----------------------------------------------------------------- .\" * MAIN CONTENT STARTS HERE * .\" ----------------------------------------------------------------- .SH "NAME" aminerremotecontrol \- lightweight tool for log checking, log analysis .SH "SYNOPSIS" .HP \w'\fBaminerremotecontrol\fR\ 'u \fBaminerremotecontrol\fR [\fB[\-\-exec\ \fR\fB\fIcommand\fR\fR\fB]\ |\ [\-\-exec\-file\ \fR\fB\fIfile\fR\fR\fB]\fR] \fB[OPTIONS]\&.\&.\&.\fR .SH "DESCRIPTION" .PP This manual page documents briefly the \fBaminerremotecontrol\fR command\&. The command executes arbitrary remote control commands in a running AMiner child process\&. As child process is usually running with lowered privileges or SELinux/AppArmor confinement, you may observe unexpected results when accessing resources outside the child process, e\&.g\&. files\&. For more details see also packaged documentation at /usr/share/doc/logdata\-anomaly\-miner\&. .SS "Example usecases:" .PP \fBPrint a property of the running AMinerConfig:\fR .RS 4 /usr/bin/aminerremotecontrol \-\-data \*(Aq["LogResourceList"]\*(Aq \-\-exec \*(Aq print_config_property(analysis_context, "%s" % remote_control_data[0])\*(Aq .RE .PP \fBPrint the complete AMinerConfig:\fR .RS 4 /usr/bin/aminerremotecontrol \-\-exec \*(Aqprint_current_config(analysis_context)\*(Aq .RE .PP \fBPrint a property of the running AMinerConfig, change it and confirm the changed value by printing it again:\fR .RS 4 /usr/bin/aminerremotecontrol \-\-data \*(Aq["Resources\&.MaxMemoryUsage", \-1]\*(Aq \-\-exec \*(Aq print_config_property(analysis_context, "%s" % remote_control_data[0])\*(Aq \-\-exec \*(Aqchange_config_property(analysis_context, "%s" % remote_control_data[0], remote_control_data[1])\*(Aq \-\-exec \*(Aq print_config_property(analysis_context, "%s" % remote_control_data[0])\*(Aq .RE .SH "OPTIONS" .PP with long options starting with two dashes (\*(Aq\-\*(Aq)\&. A summary of options is included below\&. For a complete description, see the \fBinfo\fR(1) files\&. .PP \fB\-\-control\-socket, \-c \fR\fB\fIsocket\fR\fR .RS 4 Specify the Unix domain remote control socket path, otherwise /var/run/aminer\-remote\&.socket is used\&. The socket is opened by AMiner when \*(AqRemoteControlSocket\*(Aq feature is enabled in configuration\&. As the socket is of SOCK_STREAM type, it may also be forwarded via any other stream forwarders, e\&.g\&. socat (see UNIX\-CONNECT and UNIX\-LISTEN) and SSH (see LocalForward, DynamicForward)\&. Access control is only done by file system permissions (DAC) of the socket, so make sure not to widen the access on error\&. .RE .PP \fB\-\-exec, \-e \fR\fB\fIcommand\fR\fR .RS 4 For each \-\-exec option, the next argument is sent in a separate remote execution request using additional execution data (see \-\-data)\&. The command is executed in a separate execution namespace with only some variables added to the local namespace, e\&.g\&. execution data is available as \*(Aqremote_control_data\*(Aq\&. When setting the local variable \*(AqremoteControlResponse\*(Aq within the executed command, the object is serialized using json and sent back in the response\&. .RE .PP \fB\-\-exec\-file, \-f \fR\fB\fIfile\fR\fR .RS 4 For each \-\-exec\-file option, the named file is loaded and content submitted in the very same way as if \-\-exec parameter with content as string would have been used\&. .RE .PP \fB\-\-data, \-d \fR\fB\fIdata\fR\fR .RS 4 This parameter defines a json string defining Python objects, that will be sent with all subsequent \-\-exec operations until changed again using another \-\-data option\&. Take into account, that there are size limits for the request, very large data objects may exceed those limits\&. The execution context will expose the data as variable \*(Aqremote_control_data\*(Aq\&. .RE .PP \fB\-\-string\-response, \-s\fR .RS 4 When set, aminerremotecontrol will not pass the result to repr\&. The returned object is just converted to a plain string via str(object) and the result is printed to avoid escaping of quotation marks, newlines, \&.\&.\&.\&. WARNING: This might be insecure: without escaping the printed data may contain terminal control sequences to exploit vulnerabilities or misconfiguration of your terminal to execute code with privileges of terminal or the process calling aminerremotecontrol (usually root)\&. .RE .SS "Commands" .PP \fB \fR\fB\fIchange_config_property(analysis_context,property_name,value)\fR\fR\fB \fR .RS 4 This method allows you to change properties from the AMinerConfig at runtime\&. For every property to be changed this method must be used\&. The method prints "\fIproperty_name\fR changed to \fIvalue\fR successfully\&." if the changes were successful and an individual message if the changes failed\&. .sp Read more about which properties can be changed in the \fBValid Property Names \fRsection\&. .RE .PP \fB \fR\fB\fIchange_attribute_of_registered_analysis_component(analysis_context,component_name,attribute,value)\fR\fR\fB \fR .RS 4 This method allows you to change attributes from components of the AMinerConfig at runtime\&. For every attribute to be changed this method must be used\&. The method prints "\fIcomponent_name\&.attribute \fR changed to \fIvalue\fR successfully\&. " if the changes were successful and an individual message if the changes failed\&. The type of the new \fIvalue\fR must be the same like the old value of the \fIcomponent_name\&.attribute\fR .sp \fIexample\fR: aminerremotecontrol \-\-exec "change_attribute_of_registered_analysis_component(analysis_context, \*(AqNewMatchPath\*(Aq, \*(Aqauto_include_flag\*(Aq, False)" .RE .PP \fB \fR\fB\fIrename_registered_analysis_component(analysis_context,old_component_name,new_component_name)\fR\fR\fB \fR .RS 4 Renames the component from the \fIold_component_name\fR to \fInew_component_name\fR\&. Therefore the component with the \fIold_component_name\fR is deleted from the registered components and registered with the \fInew_component_name\fR\&. .sp \fIexample\fR: aminerremotecontrol \-\-exec "rename_registered_analysis_component(analysis_context,\*(AqNewMatchPath\*(Aq,\*(AqNewMatchPathDetector\*(Aq)" .RE .PP \fB \fR\fB\fIadd_handler_to_atom_filter_and_register_analysis_component(analysis_context,atom_handler,component,component_name)\fR\fR\fB \fR .RS 4 Adds the \fIcomponent\fR to the \fIatom_filter\fR and registers it with the \fIcomponent_name\fR\&. .sp \fIexample\fR: aminerremotecontrol \-\-exec "add_handler_to_atom_filter_and_register_analysis_component(analysis_context, \*(AqAtomFilter\*(Aq, NewMatchPathDetector(analysis_context\&.aminer_config, analysis_context\&.atomizer_factory\&.atom_handler_list, auto_include_flag=True), \*(AqNewMatchPathDet\*(Aq)" .RE .PP \fB \fR\fB\fIprint_config_property(analysis_context,property_name)\fR\fR\fB \fR .RS 4 Prints the property with the \fIproperty_name\fR from the current AMinerConfig\&. .sp \fIexample\fR: aminerremotecontrol \-\-exec "print_config_property(analysis_context,\*(AqLogResourceList\*(Aq)" .RE .PP \fB \fR\fB\fIprint_attribute_of_registered_analysis_component(analysis_context,component_name, attribute)\fR\fR\fB \fR .RS 4 Prints the \fIattribute\fR of the component with the \fIcomponent_name\fR\&. .sp \fIexample\fR: aminerremotecontrol \-\-exec "print_attribute_of_registered_analysis_component(analysis_context,\*(AqNewMatchPath\*(Aq, \*(Aqauto_include_flag\*(Aq)" .RE .PP \fB \fR\fB\fIprint_current_config(analysis_context)\fR\fR\fB \fR .RS 4 Prints the current AMinerConfig\&. It is strongly recommended to use the \fB\-\-string\-response\fR parameter for better readability\&. .sp \fIexample\fR: aminerremotecontrol \-\-exec "print_current_config(analysis_context)" \-\-string\-response .RE .PP \fB \fR\fB\fIsave_current_config(analysis_context,destination_file)\fR\fR\fB \fR .RS 4 Saves the current AMinerConfig into \fIdestination_file\fR\&. \fIdestination_file\fR must have write permissions by the aminerremotecontrol process or it returns an \fBPermissionError\fR\&. .sp \fIexample\fR: aminerremotecontrol \-\-exec "save_current_config(analysis_context,\*(Aq/tmp/config\&.py\*(Aq)" .RE .PP \fB \fR\fB\fIpersist_all()\fR\fR\fB \fR .RS 4 Saves all persistence data by calling PersistenceUtil\&.persist_all()\&. .sp \fIexample\fR: aminerremotecontrol \-\-exec "persist_all()" .RE .PP \fB \fR\fB\fIcreate_backup()\fR\fR\fB \fR .RS 4 Creates a backup of the current persistence directory and saves it in {persistence_dir}/backup/{timestamp}\&. Use this preferably after persist_all()\&. .sp \fIexample\fR: aminerremotecontrol \-\-exec "create_backup()" .RE .PP \fB \fR\fB\fIlist_backups()\fR\fR\fB \fR .RS 4 Returns a list of all existing persistence backups\&. .sp \fIexample\fR: aminerremotecontrol \-\-exec "list_backups()" .RE .PP \fB \fR\fB\fIallowlist_event_in_component(analysis_context,component_name,event_data,allowlisting_data=None)\fR\fR\fB \fR .RS 4 Allowlists a path from \fIevent_data\fR with the allowlist_event\-method from the corresponding class of the component with the \fIcomponent_name\fR\&. Only the following classes support allowlisting: \fIEnhancedNewMatchPathValueComboDetector \fR, \fIMissingMatchPathValueDetector\fR, \fINewMatchPathDetector\fR and \fINewMatchPathValueComboDetector\fR\&. For most of the components no \fIallowlisting_data\fR is needed and the \fIevent_data\fR is a path\&. The \fINewMatchPathDetector\fR supports a list of multiple pathes\&. The \fIMissingMatchPathValueComboDetector\fR needs an integer as \fIallowlisting_data\fR\&. A positive value sets the interval in seconds to the value\&. \-1 sets the interval to the default value of 3600\&. A negative value removes the missingMatchPath\&. Please read the examples of this method to use the correct parameters\&. .sp \fIexample\fR: aminerremotecontrol \-\-exec "allowlist_event_in_component(analysis_context,\*(AqEnhancedNewMatchPathValueComboDetector\*(Aq,\*(Aqnew/path\*(Aq)" .sp \fIexample\fR: aminerremotecontrol \-\-exec "allowlist_event_in_component(analysis_context,\*(AqMissingMatchPathValueDetector\*(Aq,\*(Aqnew/path\*(Aq,\-11)" .sp \fIexample\fR: aminerremotecontrol \-\-exec "allowlist_event_in_component(analysis_context,\*(AqNewMatchPathDetector\*(Aq,[\*(Aqnew/path\*(Aq])" .sp \fIexample\fR: aminerremotecontrol \-\-exec "allowlist_event_in_component(analysis_context,\*(AqNewMatchPathValueComboDetector\*(Aq,\*(Aqnew/path\*(Aq)" .RE .PP \fB \fR\fB\fIdump_events_from_history(analysis_context,history_component_name,dump_event_id)\fR\fR\fB \fR .RS 4 This method returns the string representation of a history event with the \fIdump_event_id\fR\&. If no event with the \fIdump_event_id\fR could be found, the message "FAILURE: the event with \fIdump_event_id\fR could not be found!" is returned\&. \fIhistory_component_name\fR is the registered component of the class \fIVolatileLogarithmicBackoffEventHistory\fR\&. .sp \fIexample\fR: aminerremotecontrol \-\-exec "dump_events_from_history(analysis_context,\*(AqVolatileLogarithmicBackoffEventHistory\*(Aq,12)" .RE .PP \fB \fR\fB\fIignore_events_from_history(analysis_context,history_component_name,event_ids)\fR\fR\fB \fR .RS 4 This method deletes the events with the \fIevent_ids\fR from the history\&. \fIhistory_component_name\fR is the registered component of the class \fIVolatileLogarithmicBackoffEventHistory\fR\&. The number of deleted events is returned\&. .sp \fIexample\fR: aminerremotecontrol \-\-exec "ignore_events_from_history(analysis_context,\*(AqVolatileLogarithmicBackoffEventHistory\*(Aq,[12,13,15])" .RE .PP \fB \fR\fB\fIlist_events_from_history(analysis_context,history_component_name,max_event_count=None)\fR\fR\fB \fR .RS 4 This method lists \fImax_event_count\fR events from the history\&. \fIhistory_component_name\fR is the registered component of the class \fIVolatileLogarithmicBackoffEventHistory\fR\&. If \fImax_event_count\fR is None, all events from the history are returned\&. .sp \fIexample\fR: aminerremotecontrol \-\-exec "list_events_from_history(analysis_context,\*(AqVolatileLogarithmicBackoffEventHistory\*(Aq,600)" .RE .PP \fB \fR\fB\fIallowlist_events_from_history(analysis_context,history_component_name,id_spec_list,allowlisting_data=None)\fR\fR\fB \fR .RS 4 This method allowlists the events with the ids in the\fIid_spec_list\fR from the history\&. \fIhistory_component_name\fR is the registered component of the class \fIVolatileLogarithmicBackoffEventHistory\fR\&. The allowlisting response is returned\&. .sp \fIexample\fR: aminerremotecontrol \-\-exec "allowlist_events_from_history(analysis_context,\*(AqVolatileLogarithmicBackoffEventHistory\*(Aq,[12,13,15])" .RE .SS "Valid Property Names" .PP \fIMailAlerting\&.TargetAddress\fR .RS 4 \fIValue\fR: \*(AqE\-Mail Address\*(Aq .sp \fIExample\fR: aminerremotecontrol \-\-exec "change_config_property(analysis_context, \*(AqMailAlerting\&.TargetAddress\*(Aq, \*(Aqroot@localhost\*(Aq)" .sp Define a target e\-mail address to send alerts to\&. When undefined, no e\-mail notification hooks are added\&. .RE .PP \fIMailAlerting\&.FromAddress\fR .RS 4 \fIValue\fR: \*(AqE\-Mail Address\*(Aq .sp \fIExample\fR: aminerremotecontrol \-\-exec "change_config_property(analysis_context, \*(AqMailAlerting\&.FromAddress\*(Aq, \*(Aqroot@localhost\*(Aq)" .sp Sender address of e\-mail alerts\&. .RE .PP \fIMailAlerting\&.SubjectPrefix\fR .RS 4 \fIValue\fR: \*(AqString\*(Aq .sp \fIExample\fR: aminerremotecontrol \-\-exec "change_config_property(analysis_context, \*(AqMailAlerting\&.SubjectPrefix\*(Aq, \*(AqAMiner Alerts:\*(Aq)" .sp Define, which text should be prepended to the standard aminer subject\&. Defaults to "AMiner Alerts:" .RE .PP \fIMailAlerting\&.EventCollectTime\fR .RS 4 \fIValue\fR: Seconds (Integer) .sp \fIExample\fR: aminerremotecontrol \-\-exec "change_config_property(analysis_context, \*(AqMailAlerting\&.EventCollectTime\*(Aq, 10)" .sp Define how many seconds to wait after a first event triggered the alerting procedure before really sending out the e\-mail\&. In that timespan, events are collected and will be sent all using a single e\-mail\&. Defaults to 10 seconds\&. .RE .PP \fIMailAlerting\&.MinAlertGap\fR .RS 4 \fIValue\fR: Seconds (Integer) .sp \fIExample\fR: aminerremotecontrol \-\-exec "change_config_property(analysis_context, \*(AqMailAlerting\&.MinAlertGap\*(Aq, 600)" .sp Define the minimum time between two alert e\-mails in seconds to avoid spamming\&. All events during this timespan are collected and sent out with the next report\&. Defaults to 600 seconds\&. .RE .PP \fIMailAlerting\&.MaxAlertGap\fR .RS 4 \fIValue\fR: Seconds (Integer) .sp \fIExample\fR: aminerremotecontrol \-\-exec "change_config_property(analysis_context, \*(AqMailAlerting\&.MaxAlertGap\*(Aq, 1000)" .sp Define the maximum time between two alert e\-mails in seconds\&. When undefined this defaults to "MailAlerting\&.MinAlertGap"\&. Otherwise this will activate an exponential backoff to reduce messages during permanent error states by increasing the alert gap by 50% when more alert\-worthy events were recorded while the previous gap time was not yet elapsed\&. .RE .PP \fIMailAlerting\&.MaxEventsPerMessage\fR .RS 4 \fIValue\fR: Number of messages (Integer) .sp \fIExample\fR: aminerremotecontrol \-\-exec "change_config_property(analysis_context, \*(AqMailAlerting\&.MaxEventsPerMessage\*(Aq, 1000)" .sp Define how many events should be included in one alert mail at most\&. This defaults to 1000\&. .RE .PP \fILogPrefix\fR .RS 4 \fIValue\fR: \*(AqString\*(Aq .sp \fIExample\fR: aminerremotecontrol \-\-exec "change_config_property(analysis_context, \*(AqLogPrefix\*(Aq, \*(Aq Original log line: \*(Aq)" .sp Most analysis components implement the output_log_line\-property, which is True by default\&. Define a prefix to the original captured log lines\&. This defaults to \*(Aq\*(Aq\&. .RE .PP \fIResources\&.MaxMemoryUsage\fR .RS 4 \fIValue\fR: \*(AqAllowed RAM usage in Megabytes (Integer: 32\-maxSystemRAM)\*(Aq .sp \fIExample\fR: aminerremotecontrol \-\-exec "change_config_property(analysis_context, \*(AqResources\&.MaxMemoryUsage\*(Aq, \-1)" .sp This property limits the maximal possible RAM in MB which the AMiner process can use\&. Be careful at choosing the value, as a shortage of memory causes a MemoryError\&. This defaults to \-1, which means that there is no limit\&. .RE .PP \fICore\&.PersistencePeriod\fR .RS 4 \fIValue\fR: Seconds (Integer) .sp \fIExample\fR: aminerremotecontrol \-\-exec "change_config_property(analysis_context, \*(AqCore\&.PersistencePeriod\*(Aq, 300)" .sp Use this property to change the time between persisting data in analysis components\&. Defaults to 600 seconds\&. .RE .PP \fILog\&.StatisticsLevel\fR .RS 4 \fIValue\fR: Level [0, 1, 2] .sp \fIExample\fR: aminerremotecontrol \-\-exec "change_config_property(analysis_context, \*(AqLog\&.StatisticsLevel\*(Aq, 2)" .sp Change the amount of data saved in statistics\&. Possible stat\-levels are 0 for no statistics, 1 for normal statistic level and 2 for verbose statistics\&. Defaults to 1\&. .RE .PP \fILog\&.DebugLevel\fR .RS 4 \fIValue\fR: Level [0, 1, 2] .sp \fIExample\fR: aminerremotecontrol \-\-exec "change_config_property(analysis_context, \*(AqLog\&.DebugLevel\*(Aq, 2)" .sp Change the debug logging level\&. Possible debug\-levels are 0 for no logging, 1 for normal output (INFO and above), 2 for printing all debug information\&. Defaults to 1\&. .RE .PP \fILog\&.StatisticsPeriod\fR .RS 4 \fIValue\fR: Seconds (Integer) .sp \fIExample\fR: aminerremotecontrol \-\-exec "change_config_property(analysis_context, \*(AqLog\&.StatisticsPeriod\*(Aq, 360)" .sp Change how often statistics are logged and reset\&. This defaults to 3600 seconds\&. .RE .SH "FILES" .PP /var/run/aminer\-remote\&.socket .RS 4 This is the default remote control socket used when not changed using the \-\-control\-socket option\&. .RE .SH "BUGS" .PP Report bugs via your distribution\*(Aqs bug tracking system\&. For bugs in the the software trunk, report via at \m[blue]\fB\%https://bugs.launchpad.net/logdata-anomaly-miner/+filebug\fR\m[]\&. .SH "SEE ALSO" .PP \fBaminer\fR(1) .SH "AUTHOR" .PP \fBMarkus Wurzenberger\fR <\&markus\&.wurzenberger@ait\&.ac\&.at\&> .RS 4 Wrote this manpage for the Debian system\&. .RE .SH "COPYRIGHT" .br Copyright \(co 2016 Markus Wurzenberger .br .PP This manual page was written for the Debian system (and may be used by others)\&. .PP Permission is granted to copy, distribute and/or modify this document under the terms of the GNU General Public License, Version 3\&. .PP On Debian systems, the complete text of the GNU General Public License can be found in /usr/share/common\-licenses/GPL\&. .sp