docs: vm operation (#2832)

* docs: add logging documentation * docs: fix headings and table markdown * docs: add service documentation
JanssenProject · Nov 1, 2022 · 1f08119 · 1f08119
1 parent c8c30d7
commit 1f08119
Show file tree

Hide file tree

Showing 4 changed files with 226 additions and 26 deletions.
diff --git a/docs/admin/developer/interception-scripts.md b/docs/admin/developer/interception-scripts.md
@@ -14,7 +14,7 @@ specific claims to ID token or Access token etc.
 Scripts can easily be upgraded and doesn't require forking the Jans Server code
 or re-building it.
 
-# Types of Interception scripts in Jans server
+## Types of Interception scripts in Jans server
 Listed below, are custom scripts classified into various types, each of which
 represents a feature of the Jans server that can be extended as per the business
 need. Each script type is described by a java interface whose methods should be
@@ -40,7 +40,7 @@ calling external APIs
 1. UMA 2 Claims-Gathering
 
 
-# Implementation languages - Jython or pure Java
+## Implementation languages - Jython or pure Java
 
 Interception scripts are written in **[Jython](http://www.jython.org/)** or in
 **pure Java**, enabling Java or Python libraries to be imported.
@@ -62,7 +62,7 @@ Some rules:
 * Normal log will log in to `jans-auth.log`
 
 **Example pure java script**
-```
+```java
 import io.jans.model.SimpleCustomProperty;
 import io.jans.model.custom.script.model.CustomScript;
 import io.jans.model.custom.script.type.discovery.DiscoveryType;
@@ -129,8 +129,8 @@ public class Discovery implements DiscoveryType {
 
 ## Implementation in Jython
 The example below is only meant to convey the concept, we will cover the details in later parts of the documentation.
-Suppose, we are implementing an Openbanking Identity platform and we have to add business specific claims say `openbanking_intent_id` to the ID token. The custom script which will help us accomplish our goal is of the type `UpdateTokenType` where the `modifyIdToken` method has to be implemented. A sample custom script with this business logic will be as stated below :
-```
+Suppose, we are implementing an Openbanking Identity platform and we have to add business specific claims say `openbanking_intent_id` to the ID token. The custom script which will help us accomplish our goal is of the type `UpdateTokenType` where the `modifyIdToken` method has to be implemented. A sample custom script with this business logic will be as stated below:
+```python
 class UpdateToken(UpdateTokenType):
     def __init__(self, currentTimeMillis):
         self.currentTimeMillis = currentTimeMillis
@@ -218,24 +218,18 @@ value for getApiVersion is greater than 10
 
 ***
 
-### Configurable properties of a custom script
-
-```html
-<table>
-<tr><td> Name </td><td>unique identifier(name) for the custom script e.g. person_authentication_google</td></tr>
-<tr><td> Description </td><td>Description text</td></tr>
-<tr><td> Programming Languages </td><td>Python </td></tr>
-<tr><td> Level </td><td>Used in Person Authentication script type, the strength of the credential is a numerical value assigned to the custom script that is tied to the authentication method. The higher the value, the stronger it is considered. Thus, if a user has several credentials enrolled, he will be asked to present the one of them having the highest strength associated.</td></tr>
-
-<tr><td> Location type </td><td>
-<ul><li>Database - Stored in persistence (LDAP, MYSQL or PLSQL whichever applicable ) </li><li>File - stored as a file</li></ul>
- </td></tr>
-<tr><td> Interactive </td><td>
-<ul><li>Web - web application</li><li>native - mobile application</li><li>both</li></ul>
- </td></tr>
-<tr><td> Custom properties</td><td>Key - value pairs for configurable parameters like Third Party API keys, location of configuration files etc </td></tr>
- </table>
-```
+## Configurable properties of a custom script
+
+| Property | Description |
+| -------- | ----------- |
+| Name | unique identifier(name) for the custom script e.g. person_authentication_google |
+| Description | Description Text |
+| Programming Languages | Python/Java |
+| Level | Used in Person Authentication script type, the strength of the credential is a numerical value assigned to the custom script that is tied to the authentication method. The higher the value, the stronger it is considered. Thus, if a user has several credentials enrolled, he will be asked to present the one of them having the highest strength associated. |
+| Location type | <ul> <li> Database - Stored in persistence (LDAP, MYSQL or PLSQL whichever applicable ) </li><li>File - stored as a file </ul> |
+| Interactive | <ul><li>Web - web application</li><li>native - mobile application</li><li>both</li></ul> |
+| Custom Properties | Key - value pairs for configurable parameters like Third Party API keys, location of configuration files etc |
+
 
 ***
 ### Building business logic in a custom script

diff --git a/docs/admin/vm-ops/checking-service-status.md b/docs/admin/vm-ops/checking-service-status.md
@@ -5,5 +5,39 @@ tags:
   - operations
 ---
 
-This is a placeholder
+In order to debug issues, checking the Jans services may be necessary. The process to do this differs slightly between operating systems. The following examples are shown on Ubuntu 20.04; however, they should work on any operating system using systemd.
 
+## Getting list of Jans services
+
+```bash
+$ sudo systemctl list-units --all "jans*"
+UNIT                    LOAD   ACTIVE SUB     DESCRIPTION               
+jans-auth.service       loaded active running Janssen OAauth service    
+jans-config-api.service loaded active running Janssen Config API service
+jans-fido2.service      loaded active running Janssen Fido2 Service     
+jans-scim.service       loaded active running Janssen Scim service      
+
+LOAD   = Reflects whether the unit definition was properly loaded.
+ACTIVE = The high-level unit activation state, i.e. generalization of SUB.
+SUB    = The low-level unit activation state, values depend on unit type.
+
+5 loaded units listed.
+```
+
+Note: depending on your OS and the components of Jans installed, the output may be different.
+
+## Checking status of a service
+```bash
+$ sudo systemctl status jans-auth.service
+● jans-auth.service - Janssen OAauth service
+     Loaded: loaded (/etc/systemd/system/jans-auth.service; enabled; vendor preset: enabled)
+     Active: active (running) since Tue 2022-11-01 15:03:23 UTC; 1h 38min ago
+    Process: 44700 ExecStart=/opt/dist/scripts/jans-auth start (code=exited, status=0/SUCCESS)
+   Main PID: 44727 (java)
+      Tasks: 60 (limit: 4677)
+     Memory: 889.2M
+     CGroup: /system.slice/jans-auth.service
+             └─44727 /opt/jre/bin/java -server -Xms256m -Xmx928m -XX:+DisableExplicitGC -Djans.base=/etc/jans -Dserver.base=/opt/jans/jetty/jan>
+```
+
+In case of an error or a non-functional component, this is where you would find information about the component.
diff --git a/docs/admin/vm-ops/logs.md b/docs/admin/vm-ops/logs.md
@@ -5,5 +5,130 @@ tags:
   - operations
 ---
 
-This is a placeholder
+## Overview
+The Janssen logs can be viewed via SSH access to the server running the Janssen installation.
+
+## Log Levels
+The following log levels can be configured through the configuration CLI:
+
+| Log Level | Messages Logged |  
+|---------- |------------                  |  
+|Trace      | All messages                 |  
+|Debug      | Debug level and above        |  
+|Info       | Informational level and above|  
+|Warn       | Warning level and above      |  
+|Error      | Error level and above        |  
+|Fatal      | Only fatal errors            |  
+|Off        | Logging is disabled          |
+
+### Configuring Log Levels
+Use the following commands to get information on the logging module configuration:
+
+```bash
+$ /opt/jans/jans-cli/config-cli.py --info ConfigurationLogging
+# Log configuration operations
+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 schema type /opt/jans/jans-cli/config-cli.py --schema <schma>, for example /opt/jans/jans-cli/config-cli.py --schema /components/schemas/LoggingConfiguration
+
+$ /opt/jans/jans-cli/config-cli.py --schema /components/schemas/LoggingConfiguration
+# Generic configuration schema
+{
+  "loggingLevel": "TRACE",
+  "loggingLayout": "json",
+  "httpLoggingEnabled": true,
+  "disableJdkLogger": false,
+  "enabledOAuthAuditLogging": true,
+  "externalLoggerConfiguration": null,
+  "httpLoggingExcludePaths": [
+    "/auth/img",
+    "/auth/stylesheet"
+  ]
+}
+
+$ /opt/jans/jans-cli/config-cli.py --operation-id get-config-logging
+# Current log configuration
+{
+  "loggingLevel": "INFO",
+  "loggingLayout": "text",
+  "httpLoggingEnabled": false,
+  "disableJdkLogger": true,
+  "enabledOAuthAuditLogging": false,
+  "externalLoggerConfiguration": null,
+  "httpLoggingExcludePaths": null
+}
+```
+
+Let's assume we want to update logging configuration to `TRACE`. To do this, create a file `/tmp/log.json` with the following content:
+```json
+{
+  "loggingLevel": "TRACE",
+  "loggingLayout": "text",
+  "httpLoggingEnabled": false,
+  "disableJdkLogger": true,
+  "enabledOAuthAuditLogging": false,
+  "externalLoggerConfiguration": null,
+  "httpLoggingExcludePaths": null
+}
+```
+And use the PUT operation with this file as the payload:
+```
+$ /opt/jans/jans-cli/config-cli.py --operation-id put-config-logging --data /tmp/log.json
+```
+The server will now have logs set to TRACE.
+
+## Setup Logs
+The Jans setup logs are available under `/opt/jans/jans-setup/logs/`. There are several log files available involving the setup process:
+
+1. mysql.log (Only used if MySQL backend is chosen during setup)
+1. os-changes.log
+1. setup.log
+1. setup_error.log
+
+## Core Logs
+The available logs for Jans server are listed below:
+
+### Config API logs
+`/opt/jans/jetty/jans-config-api/logs/`
+
+| Log File | Description |  
+|--------- |-------------|
+| **configapi.log** | Config API main log |
+| **configapi_persistence.log** | Config API LDAP log |
+| **configapi_persistence_duration.log** | Config API LDAP operation duration log |
+| **configapi_persistence_ldap_statistics.log**| Config API LDAP statistics |
+| **[date].jetty.log** | Config API Jetty log |
+| **configapi_script.log** | Config API custom script log |
+
+### Jans Auth server logs
+`/opt/jans/jetty/jans-auth/logs/`
+
+The most important log files here are described below:
+
+1. `jans-auth.log`: This log file contains most authentication related information. Generally this is the first log to review for any authentication-related troubleshooting, like authentication failure or missing clients etc.
+1. `jans-auth_persistence.log`: This log file contains information about the Jans Auth server communicating with the persistence backend. 
+1. `jans-auth_script.log`: This log file contains debug messages printed from [interception scripts](../developer/interception-scripts.md).
+
+## Server Logs
+In some cases, it may be necessary to examine the server logs themselves.
+
+### OS Logs
+- For Debian based systems: `/var/log/syslog`
+- For RPM based systems: `/var/log/messages`
+
+### Apache2 Server Logs
+- For Debian based systems: `/var/log/apache2/`
+- For RPM based systems: `/var/log/httpd/`
+
+Apache2 logs are as follows:
+
+1. `access_log`: This log contains information about requests coming into the Jans Server, success status or requests, execution time for any request etc.     
+
+1. `error_log`: This log shows error messages if the web server encounter any issue while processing incoming requests.    
+
+1. `other_vhosts_access.log`: This log is specific to the Jans Server setup and those links which are being requested by a user from a web browser.
 
diff --git a/docs/admin/vm-ops/restarting-services.md b/docs/admin/vm-ops/restarting-services.md
@@ -5,5 +5,52 @@ tags:
   - operations
 ---
 
-This is a placeholder
+## Getting list of Jans services
 
+```bash
+$ sudo systemctl list-units --all "jans*"
+UNIT                    LOAD   ACTIVE SUB     DESCRIPTION               
+jans-auth.service       loaded active running Janssen OAauth service    
+jans-config-api.service loaded active running Janssen Config API service
+jans-fido2.service      loaded active running Janssen Fido2 Service     
+jans-scim.service       loaded active running Janssen Scim service      
+
+LOAD   = Reflects whether the unit definition was properly loaded.
+ACTIVE = The high-level unit activation state, i.e. generalization of SUB.
+SUB    = The low-level unit activation state, values depend on unit type.
+
+5 loaded units listed.
+```
+
+## Commands (Ubuntu 20.04, RHEL 8, SUSE 15)
+
+### Start
+
+``` 
+systemctl start [service name]
+```
+
+### Stop
+
+```
+systemctl stop [service name]
+```
+
+### Status
+
+```
+systemctl status [service name]
+```
+
+### Restart
+
+```
+systemctl restart [service name]
+```
+
+### Reload
+This command is used for the `apache2` and `httpd` services.
+
+```
+systemctl reload [service name]
+```