Configure Log Rotation in miniOrange IAM On-Premise

Without log rotation, miniOrange IAM log files grow continuously and can fill the disk, causing service disruption. This guide explains how log rotation is configured for both the IAM Server and miniOrange Services, where environment variables must be set, and how to verify and troubleshoot the setup.

miniOrange IAM On-Premise has two distinct logging systems:

IAM Server (Tomcat / log4j2) — controls the main catalina-moas.out log. Variables: LOG_FILE_SIZE, LOG_RETENTION_DAYS, LOG_RETENTION_SIZE.
Services (apps, IDP, Directory, and others) — each service writes its own rotating log. Variables: MO_LOGS_PATH, MO_MAX_FILE_SIZE, MO_LOGS_PERSIST_DAYS, ROOT_LOG_LEVEL, MO_LOGS_LEVEL.

All variables for both systems are set in the same environment file. The IAM Server and Services sections below cover each system in detail.

Log rotation is supported in IAM version 5.2.1 and later. For all other services, log rotation support is available starting from IAM version 4.8.

1. Where to Set Environment Variables

All log-related environment variables are set in the following file, which is created automatically during miniOrange IAM installation:

/etc/mo-idp-server.env

This file is sourced by the miniOrange service process at startup. Variables set anywhere else (such as in a shell session or in Tomcat's setenv.sh) will not be picked up reliably across all components.

How to Edit

Open the file with a text editor (sudo required):

sudo nano /etc/mo-idp-server.env

Add or update the relevant variable lines shown in the IAM Server and Services sections below.
Save the file, then restart the miniOrange IAM service for changes to take effect.

2. IAM Server Log Rotation

The IAM Server (Tomcat) uses log4j2 for log management. The configuration is defined in log4j2.xml inside the deployment.

Note: Log rotation for the IAM Server is available from miniOrange IAM On-Premise v5.2.1 and above.

Active log file (always receiving new entries):

$CATALINA_HOME/logs/catalina-moas.out

Rolled (archived) log file pattern:

$CATALINA_HOME/logs/catalina-moas.<MM-dd-yyyy>.<index>.log

Example: catalina-moas.06-06-2026.1.log (first rotation on 6 June 2026)

2.1 Environment Variables

Variable	Default	Format	What It Controls
`LOG_FILE_SIZE`	20MB	e.g. 10MB, 50MB	Maximum size of `catalina-moas.out` before a rotation is triggered. When this size is reached, the file is immediately rolled regardless of the time of day.
`LOG_RETENTION_DAYS`	7d	e.g. 3d, 14d, 30d	Rolled files whose last-modified timestamp is older than this value are deleted during the next rollover. Increase to keep logs longer; decrease to save disk space.
`LOG_RETENTION_SIZE`	2GB	e.g. 500MB, 5GB	If the combined size of all rolled `.log` files exceeds this value, the oldest rolled files are deleted one by one during the next rollover until the total drops below the limit. The active `catalina-moas.out` is never counted or deleted.

2.2 When Rotation Triggers

A rotation triggers when either of these conditions is met, whichever occurs first:

Time condition: the calendar date changes (daily at midnight).
Size condition: catalina-moas.out reaches the size set by LOG_FILE_SIZE.

OR logic:

Both conditions are checked independently. Reaching the size limit at any point during the day triggers an immediate rotation without waiting for midnight. Midnight triggers a rotation even if the file is small.

A rolled file is also deleted if EITHER retention condition is true (age OR total size), not both.

2.3 Known Limitation — Maximum 7 Rolled Files Per Day (IAM Server)

The IAM Server log4j2 configuration supports a maximum of 7 rolled files per calendar day. If catalina-moas.out rotates more than 7 times within a single day (because LOG_FILE_SIZE is set very small relative to daily log volume), log4j2 will not create an 8th file for that day.
This is a constraint of the DefaultRolloverStrategy used in the bundled log4j2.xml and is not configurable without modifying the XML.
To avoid hitting this limit: ensure LOG_FILE_SIZE is large enough that daily log output does not cause more than 7 rotations. For example, if the server produces roughly 700 MB of logs per day, set LOG_FILE_SIZE to at least 100MB.

2.4 Configuration in /etc/mo-idp-server.env

Add or update these lines in /etc/mo-idp-server.env:

# IAM Server (Tomcat) log rotation
        LOG_FILE_SIZE=20MB
        LOG_RETENTION_DAYS=7d
        LOG_RETENTION_SIZE=2GB

Restart the miniOrange IAM service after saving.

3. Services Log Rotation (Apps, IDP, Directory, etc.)

All miniOrange services share a single log4j2 configuration. Each service writes its own log into a subdirectory under MO_LOGS_PATH.

Log rotation is available for all versions of miniOrange IAM On-Premise Services.
Active log file per service:

$MO_LOGS_PATH/<service-name>/<service-name>.out

Rolled log file pattern per service:

$MO_LOGS_PATH/<service-name>/<service-name>.<MM-dd-yyyy>-<index>.log

3.1 Environment Variables

Variable	Default	Format	What It Controls
`MO_LOGS_PATH`	(required)	Absolute directory path	Base directory under which each service creates its own log subdirectory. If this variable is not set or is empty, file logging is disabled for all services — logs go to console only.
`MO_MAX_FILE_SIZE`	100 MB	e.g. 50 MB, 200 MB (space required)	Maximum size of each service active log file before rotation triggers. The same limit applies to all services. Default is 100 MB — note this is larger than the IAM Server default of 20MB.
`MO_LOGS_PERSIST_DAYS`	30	Integer (count of files)	Number of rolled files to retain per service. This is a count-based limit, not time-based. log4j2 keeps this many rolled files and deletes the oldest when a new one is created. Default is 30 files per service.
`ROOT_LOG_LEVEL`	WARN	TRACE, DEBUG, INFO, WARN, ERROR, OFF	Log verbosity for the root logger (all packages not otherwise configured). Lower levels produce significantly more log data. Recommended: WARN for production.
`MO_LOGS_LEVEL`	INFO	TRACE, DEBUG, INFO, WARN, ERROR, OFF	Log verbosity specifically for the `com.miniorange` package. Set to DEBUG when troubleshooting miniOrange-specific issues. Recommended: INFO for production.

3.2 Important: MO_LOGS_PATH Must Be Set

File logging is disabled without MO_LOGS_PATH

If MO_LOGS_PATH is not set in /etc/mo-idp-server.env, the EnvironmentArbiter in the service log4j2 configuration disables the RollingFile appender entirely. All service log output goes to console (stdout) only — no log files are written and no rotation occurs.
Set MO_LOGS_PATH to an absolute path on a partition with sufficient free space.

3.3 Effect of Log Level on Disk Usage

Setting ROOT_LOG_LEVEL or MO_LOGS_LEVEL to DEBUG or TRACE produces significantly more log output, which causes log files to grow faster and rotation to trigger more frequently. In production, use WARN for ROOT_LOG_LEVEL and INFO for MO_LOGS_LEVEL unless actively debugging an issue. Return to these levels after debugging is complete.

3.4 Configuration in /etc/mo-idp-server.env

Add or update these lines in /etc/mo-idp-server.env:

# Service log configuration
    MO_MAX_FILE_SIZE=100 MB
    MO_LOGS_PERSIST_DAYS=30
    ROOT_LOG_LEVEL=WARN
    MO_LOGS_LEVEL=INFO

Format difference for MO_MAX_FILE_SIZE: For services, the size value must include a space between the number and unit: '100 MB' not '100MB'. This matches the format in the service log4j2 configuration. Using no space may not be read correctly.
For the IAM Server (LOG_FILE_SIZE), no space is needed: '20MB'.

4. Verifying Log Rotation Is Working

4.1 IAM Server

Confirm the active log file exists and is receiving entries:

ls -lh $CATALINA_HOME/logs/catalina-moas.out
tail -20 $CATALINA_HOME/logs/catalina-moas.out

Check for rolled files (empty list is expected on a fresh installation before the first rotation):

ls -lh $CATALINA_HOME/logs/catalina-moas.*.log

Confirm the variables are set correctly:

grep -E 'LOG_FILE_SIZE|LOG_RETENTION' /etc/mo-idp-server.env

Check total log directory disk usage:

du -sh $CATALINA_HOME/logs/

To trigger a test rotation without waiting for midnight or heavy traffic: temporarily set LOG_FILE_SIZE=1MB in /etc/mo-idp-server.env, restart the service, perform one login attempt or any API call, then check for a new rolled file. Restore the original value and restart again.

4.2 Services

Confirm MO_LOGS_PATH is set:

grep MO_LOGS_PATH /etc/mo-idp-server.env

List the logs directory for a specific service (replace with actual service name):

ls -lh $MO_LOGS_PATH/<service-name>/

Confirm the active log exists and rolled files appear after first rotation:

ls -lh $MO_LOGS_PATH/<service-name>/<service-name>.out
ls -lh $MO_LOGS_PATH/<service-name>/<service-name>.*.log

5. Troubleshooting

5.1 Common Mistakes and Fixes

Symptom / Mistake	Cause and Fix
IAM Server logs never rotate	Variables are not being read. Ensure `LOG_FILE_SIZE` and `LOG_RETENTION_DAYS` are set in `/etc/mo-idp-server.env` — not in a shell session or Tomcat's `setenv.sh`. Verify the miniOrange service was fully restarted after editing the file.
Service log files are not created at all	`MO_LOGS_PATH` is not set or is empty. Without this variable, file logging is disabled for all services. Set `MO_LOGS_PATH` to a valid absolute directory path in `/etc/mo-idp-server.env` and restart.
IAM Server rotates almost immediately after startup	`LOG_FILE_SIZE` is missing the unit suffix. Example: `LOG_FILE_SIZE=20` (no unit) is interpreted as 20 bytes, causing near-continuous rotation. Always include the unit: `LOG_FILE_SIZE=20MB`.
`MO_MAX_FILE_SIZE` not respected for services	The service log4j2 configuration requires a space between the number and unit. Use `MO_MAX_FILE_SIZE=100 MB` (with space), not `100MB`. Without the space the value may not parse correctly.
Old rolled files are not being deleted	Deletion only runs during a rollover event, not on a schedule. If no rotation has occurred recently (the active file is small and midnight has not passed), stale files remain. Trigger a rotation manually to force a cleanup pass.
Active log file (`catalina-moas.out`) disappears	Do not delete the active log file while Tomcat is running. log4j2 holds an open file handle; deleting the file while the process is running causes logging to silently stop. Restart the miniOrange service to recreate the file.
Disk still full after configuring retention limits	Cleanup only runs at the next rollover. If the disk is already full, rotation cannot trigger. Manually remove old rolled files using the emergency cleanup commands below, then configure proper retention values.
IAM Server stops creating rolled files mid-day	The maximum is 7 rolled files per calendar day (see Known Limitation above). If `LOG_FILE_SIZE` is set too small for the daily log volume, this limit is reached. Increase `LOG_FILE_SIZE` so that no more than 7 rotations occur per day.
Log level change has no effect	`ROOT_LOG_LEVEL` and `MO_LOGS_LEVEL` are read at service startup. Changes to `/etc/mo-idp-server.env` require a full service restart to take effect. A SIGHUP or reload is not sufficient.

5.2 Emergency — Disk Full Right Now

Caution — do not delete the active log file.

Do NOT delete catalina-moas.out while Tomcat is running. log4j2 holds an open file handle.

Deleting the active file causes logging to stop silently until the service is restarted.

Only delete rolled .log files — files that include a date in their name.

Run these commands to identify and safely free space:


    # Total log directory size
    du -sh $CATALINA_HOME/logs/

    # List IAM rolled files, largest first
    ls -lhS $CATALINA_HOME/logs/catalina-moas.*.log

    # Delete IAM rolled files older than 3 days
    find $CATALINA_HOME/logs/ -name 'catalina-moas.*.log' -mtime +3 -delete

    # Delete service rolled files older than 3 days
    find $MO_LOGS_PATH/ -name '*.log' -mtime +3 -delete
    
    # Confirm disk space recovered
    df -h $CATALINA_HOME/logs/

After freeing space, review and update /etc/mo-idp-server.env with appropriate size and retention values, then restart the miniOrange IAM service.

6. Quick Reference

6.1 All Environment Variables

Variable	Default	Applies To	Purpose
`LOG_FILE_SIZE`	20MB	IAM Server	Rotate active log when it reaches this size
`LOG_RETENTION_DAYS`	7d	IAM Server	Delete rolled files older than this age
`LOG_RETENTION_SIZE`	2GB	IAM Server	Delete oldest rolled files if combined total exceeds this
`MO_LOGS_PATH`	(required)	Services	Base directory for service logs (required for file logging)
`MO_MAX_FILE_SIZE`	100 MB	Services	Rotate per-service active log at this size (include space: 100 MB)
`MO_LOGS_PERSIST_DAYS`	30	Services	Number of rolled files to keep per service (count, not days)
`ROOT_LOG_LEVEL`	WARN	Services	Log verbosity for all packages (root logger)
`MO_LOGS_LEVEL`	INFO	Services	Log verbosity for `com.miniorange` packages only

6.2 Log File Locations

Component	Active Log File	Rolled File Pattern
IAM Server	`$CATALINA_HOME/logs/catalina-moas.out`	`catalina-moas.MM-dd-yyyy.N.log`
Services	`$MO_LOGS_PATH/<svc>/<svc>.out`	`<svc>.MM-dd-yyyy-N.log`

6.3 Environment File

/etc/mo-idp-server.env

Created automatically during miniOrange IAM installation. Edit this file to configure all log variables. Always restart the miniOrange IAM service after changes.

Contents