diff --git a/docs/admin/config-guide/logging-configuration.md b/docs/admin/config-guide/logging-configuration.md index 8875aa63681..f1d1bf09a8e 100644 --- a/docs/admin/config-guide/logging-configuration.md +++ b/docs/admin/config-guide/logging-configuration.md @@ -7,102 +7,175 @@ tags: # Log Management -> Prerequisite: Know how to use the Janssen CLI in [command-line mode](config-tools/jans-cli/README.md) +Logging for Janssen Server modules is managed at the individual module level. +Meaning there is no single switch or configuration that will enable or disable +logs for all modules. Each module can be individually configured and can be +configured differently when it comes to logging. -To `view/update` logging configuration, let's get the information of logging Configuration. +Logging for `jans-auth` service is what we are going to discuss in detail +in this document. +Logging for other modules is configured by changing the module's +property values. Use the documentation on how to update configuration +properties for +corresponding modules to update logging related properties. For instance: -`/opt/jans/jans-cli/config-cli.py --info ConfigurationLogging` +[//]: # (TODO: not sure if the sections below exist in respective docs. But) +[//]: # (if not then we need to add this content and link it here) +- [Updating properties for Fido2 module]() +- [Updating properties for SCIM module]() + +## Log Configuration For jans-auth + +=== "Use Command-line" + + Use the command line to perform actions from the terminal. Learn how to + use Jans CLI [here](./config-tools/jans-cli/README.md) or jump straight to + the [Using Command Line](#using-command-line) + +=== "Use Text-based UI" + + Use a fully functional text-based user interface from the terminal. + Learn how to use Jans Text-based UI (TUI) + [here](./config-tools/jans-tui/README.md) or jump straight to the + [Using-text-based-ui](#using-text-based-ui) -```text -Operation ID: get-config-logging - Description: Returns Jans Authorization Server logging settings. -Operation ID: put-config-logging - Description: Updates Jans Authorization Server logging settings. - Schema: /components/schemas/LoggingConfiguration -To get sample shema type /opt/jans/jans-cli/config-cli.py --schema , for example /opt/jans/jans-cli/config-cli.py --schema /components/schemas/LoggingConfiguration +=== "Use REST API" + + Use REST API for programmatic access or invoke via tools like CURL or + Postman. Learn how to use Janssen Server Config API + [here](./config-tools/config-api/README.md) or Jump straight to the + [Using Configuration REST API](#using-configuration-rest-api) + +## Using Command Line + +In the Janssen Server, you can deploy and customize the Logging Configuration using the +command line. To get the details of Janssen command line operations relevant to +Logging configuration, you can check the operations under +`ConfigurationLogging` task using the +command below: + +```bash title="Command" +/opt/jans/jans-cli/config-cli.py --info ConfigurationLogging ``` -Table of Contents -================= +```text title="Sample Output" +Operation ID: get-config-logging + Description: Returns Jans Authorization Server logging settings +Operation ID: put-config-logging + Description: Updates Jans Authorization Server logging settings + Schema: Logging -* [Log Management](#log-management) - * [Find Logging Configuration](#find-logging-configuration) - * [Update Logging Configuration](#update-logging-configuration) +To get sample schema type /opt/jans/jans-cli/config-cli.py --schema , for example /opt/jans/jans-cli/config-cli.py --schema Logging +``` -## Find Logging Configuration +### Find Logging Configuration -```text +```bash title="Command" /opt/jans/jans-cli/config-cli.py --operation-id get-config-logging +``` -Getting access token for scope https://jans.io/oauth/config/logging.readonly +```json title="Sample Output" linenums="1" { - "loggingLevel": "INFO", - "loggingLayout": "text", - "httpLoggingEnabled": false, + "loggingLevel": "DEBUG", + "loggingLayout": "string", + "httpLoggingEnabled": true, "disableJdkLogger": true, - "enabledOAuthAuditLogging": false, - "externalLoggerConfiguration": null, - "httpLoggingExcludePaths": null + "enabledOAuthAuditLogging": true, + "externalLoggerConfiguration": "string", + "httpLoggingExcludePaths": [ + "string" + ] } + ``` -## Update Logging Configuration +### Update Logging Configuration To update logging configuration, get the schema first: +```bash title="Command" +/opt/jans/jans-cli/config-cli.py --schema Logging > /tmp/log-config.json +``` +The schema can now be found in the log-config.json file. +Check the [update logging schema model](https://gluu.org/swagger-ui/?url=https://raw.githubusercontent.com/JanssenProject/jans/vreplace-janssen-version/jans-config-api/docs/jans-config-api-swagger.yaml#/Configuration%20%E2%80%93%20Logging/put-config-logging) -```commandline -/opt/jans/jans-cli/config-cli.py --schema /components/schemas/LoggingConfiguration > /tmp/log-config.json +let's update the schema: +```bash title="Command" +nano /tmp/log-config.json +``` +As seen below, I have added `loggingLevel` for the value `INFO` +and `enabledOAuditLogging` for the value `false`. +```json title="Input" { - "loggingLevel": "FATAL", - "loggingLayout": "text", + "loggingLevel": "INFO", + "loggingLayout": "string", "httpLoggingEnabled": true, "disableJdkLogger": true, "enabledOAuthAuditLogging": false, - "externalLoggerConfiguration": null, + "externalLoggerConfiguration": "string", "httpLoggingExcludePaths": [ - "/auth/img", - "/auth/stylesheet" + "string" ] } ``` -let's update the schema: -```text -nano /tmp/log-config.json -``` - -Here I have updated `loggingLevel` to `DEBUG` and `enabledOAuditLogging` to `true` as below image. - -![updated logging](../../assets/image-cl-update-logging-03042021.png) - - Let's do the operation: -```commandline -/opt/jans/jans-cli/config-cli.py --operation-id put-config-logging --data /tmp/log-config.json +```bash title="Command" +/opt/jans/jans-cli/config-cli.py --operation-id put-config-logging \ + --data /tmp/log-config.json ``` You will get the updated result as below: -```text - -Getting access token for scope https://jans.io/oauth/config/logging.write -Server Response: +```json title="Sample Output" linenums="1" { - "loggingLevel": "DEBUG", - "loggingLayout": "json", - "httpLoggingEnabled": false, - "disableJdkLogger": false, - "enabledOAuthAuditLogging": true, - "externalLoggerConfiguration": null, + "loggingLevel": "INFO", + "loggingLayout": "string", + "httpLoggingEnabled": true, + "disableJdkLogger": true, + "enabledOAuthAuditLogging": false, + "externalLoggerConfiguration": "string", "httpLoggingExcludePaths": [ - "/auth/img", - "/auth/stylesheet" + "string" ] } ``` +## Using-text-based-ui + +In Janssen, You can manage Logging configuration using +the [Text-Based UI](./config-tools/jans-tui/README.md) also. + +You can start TUI using the command below: + +```bash title="Command" +sudo /opt/jans/jans-cli/jans_cli_tui.py +``` +### Logging Screen + +* Navigate to `Auth Server` -> `Logging` to open the Logging screen as shown +in the image below. + +* Logging screen allows the administrator to set logging parameters as per +the requirements. + + +![image](../../assets/tui-logging-config.png) + +## Using Configuration REST API + +Janssen Server Configuration REST API exposes relevant endpoints for managing +and configuring logging. Endpoint details are published in the [Swagger +document](./../reference/openapi.md). + +## Default Log Location + +On a VM installation, logs for `jans-auth` module are generated at +`/opt/jans/jetty/jans-auth/logs/`. + +## Cloud-Native Deployments +Logging configuration for a cloud-native deployment is [detailed here](../kubernetes-ops/logs.md) \ No newline at end of file diff --git a/docs/assets/tui-logging-config.png b/docs/assets/tui-logging-config.png new file mode 100644 index 00000000000..3eb64f452ff Binary files /dev/null and b/docs/assets/tui-logging-config.png differ