Provided by: logdata-anomaly-miner_2.6.0-1_all bug

NAME

       aminerremotecontrol - lightweight tool for log checking, log analysis

SYNOPSIS

       aminerremotecontrol [[--exec command] | [--exec-file file ]] [OPTIONS]...

DESCRIPTION

       This manual page documents briefly the aminerremotecontrol 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.

   Example usecases:
       Print a property of the running AminerConfig:
           /usr/bin/aminerremotecontrol --data '["LogResourceList"]' --exec '
           print_config_property(analysis_context, "%s" % remote_control_data[0])'

       Print the complete AminerConfig:
           /usr/bin/aminerremotecontrol --exec 'print_current_config(analysis_context)'

       Print a property of the running AminerConfig, change it and confirm the changed value by
       printing it again:
           /usr/bin/aminerremotecontrol --data '["Resources.MaxMemoryUsage", -1]' --exec '
           print_config_property(analysis_context, "%s" % remote_control_data[0])' --exec
           'change_config_property(analysis_context, "%s" % remote_control_data[0],
           remote_control_data[1])' --exec ' print_config_property(analysis_context, "%s" %
           remote_control_data[0])'

OPTIONS

       with long options starting with two dashes ('-'). A summary of options is included below.
       For a complete description, see the info(1) files.

       --control-socket, -c socket
           Specify the Unix domain remote control socket path, otherwise
           /var/run/aminer-remote.socket is used. The socket is opened by aminer when
           'RemoteControlSocket' 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.

       --exec, -e command
           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 'remote_control_data'. When setting the local
           variable 'remoteControlResponse' within the executed command, the object is serialized
           using json and sent back in the response.

       --exec-file, -f file
           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.

       --data, -d data
           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
           'remote_control_data'.

       --string-response, -s
           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).

   Commands
        change_config_property(analysis_context,'property_name','value')
           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
           "property_name changed to value successfully." if the changes were successful and an
           individual message if the changes failed.

           Read more about which properties can be changed in the Valid Property Names section.

        change_attribute_of_registered_analysis_component(analysis_context,'component_name','attribute','value')
           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
           "component_name.attribute changed to value successfully. " if the changes were
           successful and an individual message if the changes failed. The type of the new value
           must be the same like the old value of the component_name.attribute

           example: aminerremotecontrol --exec
           "change_attribute_of_registered_analysis_component(analysis_context,
           'NewMatchPath','learn_mode', False)"

        rename_registered_analysis_component(analysis_context,'old_component_name','new_component_name')
           Renames the component from the old_component_name to new_component_name. Therefore the
           component with the old_component_name is deleted from the registered components and
           registered with the new_component_name.

           example: aminerremotecontrol --exec
           "rename_registered_analysis_component(analysis_context,'NewMatchPath','NewMatchPathDetector')"

        add_handler_to_atom_filter_and_register_analysis_component(analysis_context,'atom_handler',component,'component_name')
           Adds the component to the atom_filter and registers it with the component_name.

           example: aminerremotecontrol --exec
           "add_handler_to_atom_filter_and_register_analysis_component(analysis_context,'AtomFilter',
           NewMatchPathDetector(analysis_context.aminer_config,
           analysis_context.atomizer_factory.atom_handler_list,
           learn_mode=True),'NewMatchPathDet')"

        print_config_property(analysis_context,'property_name')
           Prints the property with the property_name from the current AminerConfig.

           example: aminerremotecontrol --exec
           "print_config_property(analysis_context,'LogResourceList')"

        print_attribute_of_registered_analysis_component(analysis_context,'component_name','attribute')
           Prints the attribute of the component with the component_name.

           example: aminerremotecontrol --exec
           "print_attribute_of_registered_analysis_component(analysis_context,'NewMatchPath','learn_mode')"

        print_current_config(analysis_context)
           Prints the current AminerConfig. It is strongly recommended to use the
           --string-response parameter for better readability.

           example: aminerremotecontrol --exec "print_current_config(analysis_context)"
           --string-response

        save_current_config(analysis_context,'destination_file')
           Saves the current AminerConfig into destination_file.  destination_file must have
           write permissions by the aminerremotecontrol process or it returns an PermissionError.

           example: aminerremotecontrol --exec
           "save_current_config(analysis_context,'/tmp/config.py')"

        persist_all()
           Saves all persistence data by calling PersistenceUtil.persist_all().

           example: aminerremotecontrol --exec "persist_all()"

        create_backup()
           Creates a backup of the current persistence directory and saves it in
           {persistence_dir}/backup/{timestamp}. Use this preferably after persist_all().

           example: aminerremotecontrol --exec "create_backup()"

        list_backups()
           Returns a list of all existing persistence backups.

           example: aminerremotecontrol --exec "list_backups()"

        allowlist_event_in_component(analysis_context,'component_name',event_data,allowlisting_data=None)
           Allowlists a path from event_data with the allowlist_event-method from the
           corresponding class of the component with the component_name. Only the following
           classes support allowlisting: EnhancedNewMatchPathValueComboDetector,
           MissingMatchPathValueDetector, NewMatchPathDetector and
           NewMatchPathValueComboDetector. For most of the components no allowlisting_data is
           needed and the event_data is a path. The NewMatchPathDetector supports a list of
           multiple pathes. The MissingMatchPathValueComboDetector needs an integer as
           allowlisting_data. 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.

           example: aminerremotecontrol --exec
           "allowlist_event_in_component(analysis_context,'EnhancedNewMatchPathValueComboDetector','new/path')"

           example: aminerremotecontrol --exec
           "allowlist_event_in_component(analysis_context,'MissingMatchPathValueDetector','new/path',-11)"

           example: aminerremotecontrol --exec
           "allowlist_event_in_component(analysis_context,'NewMatchPathDetector',['new/path'])"

           example: aminerremotecontrol --exec
           "allowlist_event_in_component(analysis_context,'NewMatchPathValueComboDetector','new/path')"

        dump_events_from_history(analysis_context,'history_component_name',dump_event_id)
           This method returns the string representation of a history event with the
           dump_event_id. If no event with the dump_event_id could be found, the message
           "FAILURE: the event with dump_event_id could not be found!" is returned.
           history_component_name is the registered component of the class
           VolatileLogarithmicBackoffEventHistory.

           example: aminerremotecontrol --exec
           "dump_events_from_history(analysis_context,'VolatileLogarithmicBackoffEventHistory',12)"

        ignore_events_from_history(analysis_context,'history_component_name',event_ids)
           This method deletes the events with the event_ids from the history.
           history_component_name is the registered component of the class
           VolatileLogarithmicBackoffEventHistory. The number of deleted events is returned.

           example: aminerremotecontrol --exec
           "ignore_events_from_history(analysis_context,'VolatileLogarithmicBackoffEventHistory',[12,13,15])"

        list_events_from_history(analysis_context,'history_component_name',max_event_count=None)
           This method lists max_event_count events from the history.  history_component_name is
           the registered component of the class VolatileLogarithmicBackoffEventHistory. If
           max_event_count is None, all events from the history are returned.

           example: aminerremotecontrol --exec
           "list_events_from_history(analysis_context,'VolatileLogarithmicBackoffEventHistory',600)"

        allowlist_events_from_history(analysis_context,'history_component_name',id_spec_list,allowlisting_data=None)
           This method allowlists the events with the ids in theid_spec_list from the history.
           history_component_name is the registered component of the class
           VolatileLogarithmicBackoffEventHistory. The allowlisting response is returned.

           example: aminerremotecontrol --exec
           "allowlist_events_from_history(analysis_context,'VolatileLogarithmicBackoffEventHistory',[12,13,15])"

        reopen_event_handler_streams(analysis_context)
           Reopen all StreamPrinterEventHandler streams for log rotation.

           example: aminerremotecontrol --exec "reopen_event_handler_streams(analysis_context)"

   Valid Property Names
       MailAlerting.TargetAddress
           Value: 'E-Mail Address'

           Example: aminerremotecontrol --exec
           "change_config_property(analysis_context,'MailAlerting.TargetAddress',
           'root@localhost')"

           Define a target e-mail address to send alerts to. When undefined, no e-mail
           notification hooks are added.

       MailAlerting.FromAddress
           Value: 'E-Mail Address'

           Example: aminerremotecontrol --exec
           "change_config_property(analysis_context,'MailAlerting.FromAddress',
           'root@localhost')"

           Sender address of e-mail alerts.

       MailAlerting.SubjectPrefix
           Value: 'String'

           Example: aminerremotecontrol --exec
           "change_config_property(analysis_context,'MailAlerting.SubjectPrefix', 'aminer
           Alerts:')"

           Define, which text should be prepended to the standard aminer subject. Defaults to
           "aminer Alerts:"

       MailAlerting.EventCollectTime
           Value: Seconds (Integer)

           Example: aminerremotecontrol --exec
           "change_config_property(analysis_context,'MailAlerting.EventCollectTime', 10)"

           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.

       MailAlerting.MinAlertGap
           Value: Seconds (Integer)

           Example: aminerremotecontrol --exec
           "change_config_property(analysis_context,'MailAlerting.MinAlertGap', 600)"

           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.

       MailAlerting.MaxAlertGap
           Value: Seconds (Integer)

           Example: aminerremotecontrol --exec
           "change_config_property(analysis_context,'MailAlerting.MaxAlertGap', 1000)"

           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.

       MailAlerting.MaxEventsPerMessage
           Value: Number of messages (Integer)

           Example: aminerremotecontrol --exec
           "change_config_property(analysis_context,'MailAlerting.MaxEventsPerMessage',1000)"

           Define how many events should be included in one alert mail at most. This defaults to
           1000.

       LogPrefix
           Value: 'String'

           Example: aminerremotecontrol --exec
           "change_config_property(analysis_context,'LogPrefix','Original log line: ')"

           Most analysis components implement the output_logline-property, which is True by
           default. Define a prefix to the original captured log lines. This defaults to ''.

       Resources.MaxMemoryUsage
           Value: 'Allowed RAM usage in Megabytes (Integer: 32-maxSystemRAM)'

           Example: aminerremotecontrol --exec
           "change_config_property(analysis_context,'Resources.MaxMemoryUsage', -1)"

           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.

       Core.PersistencePeriod
           Value: Seconds (Integer)

           Example: aminerremotecontrol --exec
           "change_config_property(analysis_context,'Core.PersistencePeriod', 300)"

           Use this property to change the time between persisting data in analysis components.
           Defaults to 600 seconds.

       Log.StatisticsLevel
           Value: Level [0, 1, 2]

           Example: aminerremotecontrol --exec
           "change_config_property(analysis_context,'Log.StatisticsLevel',2)"

           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.

       Log.DebugLevel
           Value: Level [0, 1, 2]

           Example: aminerremotecontrol --exec
           "change_config_property(analysis_context,'Log.DebugLevel',2)"

           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.

       Log.StatisticsPeriod
           Value: Seconds (Integer)

           Example: aminerremotecontrol --exec
           "change_config_property(analysis_context,'Log.StatisticsPeriod', 360)"

           Change how often statistics are logged and reset. This defaults to 3600 seconds.

FILES

       /var/run/aminer-remote.socket
           This is the default remote control socket used when not changed using the
           --control-socket option.

BUGS

       Report bugs via your distribution's bug tracking system. For bugs in the the software
       trunk, report via at https://bugs.launchpad.net/logdata-anomaly-miner/+filebug.

SEE ALSO

       aminer(1)

AUTHOR

       Markus Wurzenberger <markus.wurzenberger@ait.ac.at>
           Wrote this manpage for the Debian system.

COPYRIGHT

       Copyright © 2016 Markus Wurzenberger

       This manual page was written for the Debian system (and may be used by others).

       Permission is granted to copy, distribute and/or modify this document under the terms of
       the GNU General Public License, Version 3.

       On Debian systems, the complete text of the GNU General Public License can be found in
       /usr/share/common-licenses/GPL.