Comment 2 for bug 1336462

Revision history for this message
Thierry FAUCK (thierry-j) wrote :

Found that package-hooks.txt.gz exists.
Package independent hooks
=========================

Similarly to per-package hooks, you can also have additional
information collected for any crash or bug. For example, you might
want to include violation logs from SELinux or AppArmor for every
crash. The interface and file format is identical to the per-package
hooks, except that they need to be put into

  /usr/share/apport/general-hooks/<hookname>.py

The <hookname> can be arbitrary and should describe the functionality.

Standard hook functions
=======================

If you write hooks, please have a look at the apport.hookutils
module first:

Functions of interest:
-------------------------------
    attach_file(report, path, key=None, overwrite=True, force_unicode=False)
        Attach a file to the report.

        If key is not specified, the key name will be derived from the file
        name with path_to_key().

        If overwrite is True, an existing key will be updated. If it is False, a
        new key with '_' appended will be added instead.

        If the contents is valid UTF-8, or force_unicode is True, then the value
        will a string, otherwise it will be bytes.

    attach_file_if_exists(report, path, key=None, overwrite=True, force_unicode=False)
        Attach file contents if file exists.

        If key is not specified, the key name will be derived from the file
        name with path_to_key().

        If overwrite is True, an existing key will be updated. If it is False, a
        new key with '_' appended will be added instead.

        If the contents is valid UTF-8, or force_unicode is True, then the value
        will a string, otherwise it will be bytes.
    attach_root_command_outputs(report, command_map)
        Execute multiple commands as root and put their outputs into report.

        command_map is a keyname -> 'shell command' dictionary with the commands to
        run. They are all run through /bin/sh, so you need to take care of shell
        escaping yourself. To include stderr output of a command, end it with
        "2>&1".

        Just like root_command_output, this passes the command through pkexec,
        unless the caller is already root.

        This is preferrable to using root_command_output() multiple times, as that
        will ask for the password every time.
    command_available(command)
        Is given command on the executable search path?

    command_output(command, input=None, stderr=-2, keep_locale=False, decode_utf8=True)
        Try to execute given command (array) and return its stdout.

        In case of failure, a textual error gets returned. This function forces
        LC_MESSAGES to C, to avoid translated output in bug reports.

        If decode_utf8 is True (default), the output will be converted to a string,
        otherwise left as bytes.
    read_file(path, force_unicode=False)
        Return the contents of the specified path.

        If the contents is valid UTF-8, or force_unicode is True, then the value
        will a string, otherwise it will be bytes.

        Upon error, this will deliver a text representation of the error,
        instead of failing.
    root_command_output(command, input=None, stderr=-2, decode_utf8=True)
        Try to execute given command (array) as root and return its stdout.

        This passes the command through pkexec, unless the caller is already root.

        In case of failure, a textual error gets returned.

        If decode_utf8 is True (default), the output will be converted to a string,
        otherwise left as bytes.

Example of use:
-----------------------
 python -c 'import apport.hookutils; help(apport.hookutils)'
    apport.hookutils.attach_alsa(report)
    ui.information('Now playing test sound...')

    report['AplayOut'] = apport.hookutils.command_output(['aplay',
     '/usr/share/sounds/question.wav'])