|
| 1 | +#!/opt/venvs/securedrop-log/bin/python3 |
| 2 | +"""A skeleton for a Python rsyslog output plugin with error handling. |
| 3 | +Requires Python 3. |
| 4 | +
|
| 5 | +To integrate a plugin based on this skeleton with rsyslog, configure an |
| 6 | +'omprog' action like the following: |
| 7 | + action(type="omprog" |
| 8 | + binary="/usr/bin/myplugin.py" |
| 9 | + output="/var/log/myplugin.log" |
| 10 | + confirmMessages="on" |
| 11 | + ...) |
| 12 | +
|
| 13 | +Licensed under the Apache License, Version 2.0 (the "License"); |
| 14 | +you may not use this file except in compliance with the License. |
| 15 | +You may obtain a copy of the License at |
| 16 | +
|
| 17 | + http://www.apache.org/licenses/LICENSE-2.0 |
| 18 | + -or- |
| 19 | + see COPYING.ASL20 in the source distribution |
| 20 | +
|
| 21 | +Unless required by applicable law or agreed to in writing, software |
| 22 | +distributed under the License is distributed on an "AS IS" BASIS, |
| 23 | +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 24 | +See the License for the specific language governing permissions and |
| 25 | +limitations under the License. |
| 26 | +""" |
| 27 | + |
| 28 | +import sys |
| 29 | +import os |
| 30 | +import logging |
| 31 | +import configparser |
| 32 | +from subprocess import Popen, PIPE |
| 33 | + |
| 34 | +# Global definitions specific to your plugin |
| 35 | +process = None |
| 36 | + |
| 37 | +class RecoverableError(Exception): |
| 38 | + """An error that has caused the processing of the current message to |
| 39 | + fail, but does not require restarting the plugin. |
| 40 | +
|
| 41 | + An example of such an error would be a temporary loss of connection to |
| 42 | + a database or a server. If such an error occurs in the onMessage function, |
| 43 | + your plugin should wrap it in a RecoverableError before raising it. |
| 44 | + For example: |
| 45 | +
|
| 46 | + try: |
| 47 | + # code that connects to a database |
| 48 | + except DbConnectionError as e: |
| 49 | + raise RecoverableError from e |
| 50 | +
|
| 51 | + Recoverable errors will cause the 'omprog' action to be temporarily |
| 52 | + suspended by rsyslog, during a period that can be configured using the |
| 53 | + "action.resumeInterval" action parameter. When the action is resumed, |
| 54 | + rsyslog will resend the failed message to your plugin. |
| 55 | + """ |
| 56 | + |
| 57 | + |
| 58 | +def onInit(): |
| 59 | + """Do everything that is needed to initialize processing (e.g. open files, |
| 60 | + create handles, connect to systems...). |
| 61 | + """ |
| 62 | + # Apart from processing the logs received from rsyslog, you want your plugin |
| 63 | + # to be able to report its own logs in some way. This will facilitate |
| 64 | + # diagnosing problems and debugging your code. Here we set up the standard |
| 65 | + # Python logging system to output the logs to stderr. In the rsyslog |
| 66 | + # configuration, you can configure the 'omprog' action to capture the stderr |
| 67 | + # of your plugin by specifying the action's "output" parameter. |
| 68 | + logging.basicConfig(stream=sys.stderr, |
| 69 | + level=logging.WARNING, |
| 70 | + format='%(asctime)s %(levelname)s %(message)s') |
| 71 | + |
| 72 | + # This is an example of a debug log. (Note that for debug logs to be |
| 73 | + # emitted you must set 'level' to logging.DEBUG above.) |
| 74 | + logging.debug("onInit called") |
| 75 | + |
| 76 | + |
| 77 | + global process |
| 78 | + if not os.path.exists("/etc/sd-rsyslog.conf"): |
| 79 | + print("Please create the configuration file at /etc/sd-rsyslog.conf", file=sys.stderr) |
| 80 | + sys.exit(1) |
| 81 | + config = configparser.ConfigParser() |
| 82 | + config.read('/etc/sd-rsyslog.conf') |
| 83 | + logvmname = config['sd-rsyslog']['remotevm'] |
| 84 | + localvmname = config['sd-rsyslog']['localvm'] |
| 85 | + process = Popen( |
| 86 | + ["/usr/lib/qubes/qrexec-client-vm", logvmname, "securedrop.Log"], |
| 87 | + stdin=PIPE, |
| 88 | + stdout=PIPE, |
| 89 | + stderr=PIPE, |
| 90 | + ) |
| 91 | + process.stdin.write(localvmname.encode("utf-8")) |
| 92 | + process.stdin.write(b"\n") |
| 93 | + process.stdin.flush() |
| 94 | + |
| 95 | + |
| 96 | +def onMessage(msg): |
| 97 | + """Process one log message received from rsyslog (e.g. send it to a |
| 98 | + database). If this function raises an error, the message will be retried |
| 99 | + by rsyslog. |
| 100 | +
|
| 101 | + Args: |
| 102 | + msg (str): the log message. Does NOT include a trailing newline. |
| 103 | +
|
| 104 | + Raises: |
| 105 | + RecoverableError: If a recoverable error occurs. The message will be |
| 106 | + retried without restarting the plugin. |
| 107 | + Exception: If a non-recoverable error occurs. The plugin will be |
| 108 | + restarted before retrying the message. |
| 109 | + """ |
| 110 | + logging.debug("onMessage called") |
| 111 | + |
| 112 | + # For illustrative purposes, this plugin skeleton appends the received logs |
| 113 | + # to a file. When implementing your plugin, remove the following code. |
| 114 | + global process |
| 115 | + process.stdin.write(msg.encode("utf-8")) |
| 116 | + process.stdin.write(b"\n") |
| 117 | + process.stdin.flush() |
| 118 | + |
| 119 | + |
| 120 | +def onExit(): |
| 121 | + """Do everything that is needed to finish processing (e.g. close files, |
| 122 | + handles, disconnect from systems...). This is being called immediately |
| 123 | + before exiting. |
| 124 | +
|
| 125 | + This function should not raise any error. If it does, the error will be |
| 126 | + logged as a warning and ignored. |
| 127 | + """ |
| 128 | + logging.debug("onExit called") |
| 129 | + |
| 130 | + # For illustrative purposes, this plugin skeleton appends the received logs |
| 131 | + # to a file. When implementing your plugin, remove the following code. |
| 132 | + global process |
| 133 | + process.stdin.flush() |
| 134 | + |
| 135 | + |
| 136 | +""" |
| 137 | +------------------------------------------------------- |
| 138 | +This is plumbing that DOES NOT need to be CHANGED |
| 139 | +------------------------------------------------------- |
| 140 | +This is the main loop that receives messages from rsyslog via stdin, |
| 141 | +invokes the above entrypoints, and provides status codes to rsyslog |
| 142 | +via stdout. In most cases, modifying this code should not be necessary. |
| 143 | +""" |
| 144 | +try: |
| 145 | + onInit() |
| 146 | +except Exception as e: |
| 147 | + # If an error occurs during initialization, log it and terminate. The |
| 148 | + # 'omprog' action will eventually restart the program. |
| 149 | + logging.exception("Initialization error, exiting program") |
| 150 | + sys.exit(1) |
| 151 | + |
| 152 | +# Tell rsyslog we are ready to start processing messages: |
| 153 | +print("OK", flush=True) |
| 154 | + |
| 155 | +endedWithError = False |
| 156 | +try: |
| 157 | + line = sys.stdin.readline() |
| 158 | + while line: |
| 159 | + line = line.rstrip('\n') |
| 160 | + try: |
| 161 | + onMessage(line) |
| 162 | + status = "OK" |
| 163 | + except RecoverableError as e: |
| 164 | + # Any line written to stdout that is not a status code will be |
| 165 | + # treated as a recoverable error by 'omprog', and cause the action |
| 166 | + # to be temporarily suspended. In this skeleton, we simply return |
| 167 | + # a one-line representation of the Python exception. (If debugging |
| 168 | + # is enabled in rsyslog, this line will appear in the debug logs.) |
| 169 | + status = repr(e) |
| 170 | + # We also log the complete exception to stderr (or to the logging |
| 171 | + # handler(s) configured in doInit, if any). |
| 172 | + logging.exception(e) |
| 173 | + |
| 174 | + # Send the status code (or the one-line error message) to rsyslog: |
| 175 | + print(status, flush=True) |
| 176 | + line = sys.stdin.readline() |
| 177 | + |
| 178 | +except Exception: |
| 179 | + # If a non-recoverable error occurs, log it and terminate. The 'omprog' |
| 180 | + # action will eventually restart the program. |
| 181 | + logging.exception("Unrecoverable error, exiting program") |
| 182 | + endedWithError = True |
| 183 | + |
| 184 | +try: |
| 185 | + onExit() |
| 186 | +except Exception: |
| 187 | + logging.warning("Exception ignored in onExit", exc_info=True) |
| 188 | + |
| 189 | +if endedWithError: |
| 190 | + sys.exit(1) |
| 191 | +else: |
| 192 | + sys.exit(0) |
| 193 | + |
0 commit comments