Key Manager Server Logging Configuration

This section provides information about configuring custom logging settings for Key Manager Servers:

Setting up custom logging.
Examples for logging audit and alert messages to syslog.
Reverting to default logging settings.

Key Manager Servers store information about Key Manager events in their local syslog. Such events include, for example, API logins, and performed management jobs.

You can review the default log-level settings in /opt/sshmgr/app/settings.py, in the LOGGING_DEFAULT dictionary. Here is a snippet of the dictionary:

LOGGING_DEFAULT = {

    ... ...

    'loggers': {
        # Only log warnings from the authentication module
        'django_ssl_auth': {
            'handlers': ['syslog'],
            'propagate': True,
            'level': 'WARNING',
        },
         # Only log errors from license module
        'sshmgr.license': {
            'handlers': ['syslog'],
            'propagate': True,
            'level': 'ERROR',
        },
        # Only log errors from worker
        'sshmgrbackend': {
            'handlers': ['syslog'],
            'propagate': True,
            'level': 'ERROR',
        },

    ... ...

}

To change the logging behavior of a Key Manager Server, create a separate LOGGING dictionary (instead of directly modifying settings.py). Your custom LOGGING dictionary should be defined in a separate file as not to be overwritten by upgrades.

To set up custom logging, perform the following on all the Key Manager Servers where logging behavior needs to be changed:

Create a new Python file for storing the custom LOGGING dictionary. For example,
```
/opt/sshmgr/app/loggingsettings.py
```
This file will be referred to as loggingsettings.py in the following steps.

Ensure that the loggingsettings.py file has the same ownership and permissions as the localsettings.py file:

# chown --reference=/opt/sshmgr/app/localsettings.py \
/opt/sshmgr/app/loggingsettings.py
# chmod --reference=/opt/sshmgr/app/localsettings.py \
/opt/sshmgr/app/loggingsettings.py

Add lines like the following to the loggingsettings.py file to import and define the necessary logging settings:
```
from localsettings import DEBUG

LOGGING_FORMAT = 'sshmgr[%(process)d] %(levelname)s: %(message)s'
LOGGING_HANDLERS = ['syslog']
SCRIPTBASED_DEBUG = False
SYSLOG_FACILITY = 'user'
SYSLOG_ADDRESS = '/dev/log'
SSHMGR_JOBSCHED_DEBUG = False
```
You may modify the example values:
- LOGGING_FORMAT: A string specifying the log-message format. May include Django LogRecord attributes such as %(process)d, %(levelname)s, and %(message)s. For a comprehensive list of LogRecord attributes, refer to Django documentation.
- LOGGING_HANDLERS: A list specifying the logging handlers that Key Manager uses. Include 'syslog' to log to syslog. Include 'console' to log to terminal. For example: ['syslog', 'console']
For example, the default value:
```
LOGGING_FORMAT = 'sshmgr[%(process)d] %(levelname)s: %(message)s'
```
Results in log messages similar to the following:
```
Oct 12 10:35:16 keymanager sshmgr-backend[26767] INFO: JOBSCHED Process exited, Pid: 27640, Exit value: 0
```
- SCRIPTBASED_DEBUG: Set to True for verbose logging about functions associated with script-based scans.
- SYSLOG_FACILITY: A string specifying the syslog facility used by Key Manager.
- SYSLOG_ADDRESS: A string specifying the path to the syslog socket. This is typically located at /dev/log

Copy the entire LOGGING_DEFAULT dictionary from /opt/sshmgr/app/settings.py, and append it to loggingsettings.py as LOGGING.

Your loggingsettings.py should look similar to the following:

from localsettings import DEBUG

LOGGING_FORMAT = 'sshmgr[%(process)d] %(levelname)s: %(message)s'
LOGGING_HANDLERS = ['syslog']
SCRIPTBASED_DEBUG = False
SYSLOG_FACILITY = 'user'
SYSLOG_ADDRESS = '/dev/log'
LOGGING_HANDLERS = ['syslog']
SSHMGR_JOBSCHED_DEBUG = False

LOGGING = {

    ... ...

'loggers': {
        # Only log warnings from the authentication module
        'django_ssl_auth': {
            'handlers': LOGGING_HANDLERS,
            'propagate': True,
            'level': 'WARNING',
        },
         # Only log errors from license module
        'sshmgr.license': {
            'handlers': LOGGING_HANDLERS,
            'propagate': True,
            'level': 'ERROR',
        },
        # Only log errors from worker
        'sshmgrbackend': {
            'handlers': LOGGING_HANDLERS,
            'propagate': True,
            'level': 'ERROR',
        },

    ... ...

}

In the Key Manager Server local-settings file /opt/sshmgr/app/localsettings.py, append a line like the following to import your custom LOGGING settings:
```
from loggingsettings import LOGGING
```
To start using the custom logging settings, restart the Key Manager services running on the Key Manager Server. The commands for restarting the back-end and the front-end services are as follows:
```
# supervisorctl restart backend:
# supervisorctl restart frontend:
```
note
Changing the logging settings will only affect how events are logged on the current Key Manager Server. You will have to perform this procedure on all the Key Manager Servers where the logging settings are to be updated.

You may now modify the LOGGING dictionary in loggingsettings.py to define custom logging settings for the Key Manager Server.

As an example, by default Key Manager Servers only log errors from audit events to syslog, and alert messages are not logged to syslog at all. To log all Key Manager audit and alert messages to syslog, define the following loggers in loggingsettings.py:

LOGGING = {
    ...
    # Log alerts to syslog
    'sshmgr.alert': {
        'handlers': ['syslog'],
        'propagate': False,
        'level': 'INFO',
    },
    # Log all audit events to syslog
    'sshmgr.audit': {
        'handlers': ['syslog'],
        'propagate': False,
        'level': 'INFO',
    },
    ...
}

Restart the Key Manager Server services to apply the changes:

# supervisorctl restart backend:
# supervisorctl restart frontend:

The Key Manager Server now logs all audit and alert messages to syslog.

Key Manager uses the Python built-in logging module for configuring and performing logging. For more information about configuring loggers, please see Python's documentation about the logging module. For Django-specific loggers, please see Django's documentation.

If you ever need to reset the logging settings to default values:

In /opt/sshmgr/app/localsettings.py, remove (or comment-out) the line that imports custom logging settings.
```
from loggingsettings import LOGGING
```
Save your changes to the /opt/sshmgr/app/localsettings.py file.

Restart the Key Manager Server services to apply the changes:

# supervisorctl restart backend:
# supervisorctl restart frontend: