Categories

Enable Detailed User Activity Logging in Nextcloud

Introduction: Why Detailed User Activity Logging Matters in Nextcloud

Nextcloud has become the go-to self-hosted cloud solution for organizations and individuals who value data sovereignty and privacy. However, running your own cloud infrastructure comes with responsibilities—chief among them is maintaining visibility into what users are doing on your platform. Whether you need to track login attempts, monitor who accessed which files, or see when files were shared, Nextcloud provides powerful tools to log detailed user activity.

This guide walks you through enabling and configuring comprehensive user activity logging in Nextcloud using the admin_audit app. By the end, you will have a dedicated log file with proper rotation, capturing user logins, file access, sharing events, and filesystem operations. This setup is essential for security monitoring, troubleshooting user issues, and maintaining operational oversight of your Nextcloud instance.

Note: The commands and examples in this guide assume an Apache2 with mod_fcgid setup. If you are running PHP-FPM, you will also need to restart your PHP-FPM service after making configuration changes.

What Is User Activity Logging in Nextcloud?

Nextcloud offers several ways to track user activity, but the most comprehensive solution is the admin_audit app. This official application provides detailed logging of user-driven actions that go far beyond the standard error logging in nextcloud.log.

What User Activities Can You Track?

• User Logins and Logouts: See who logged in, when, from which IP address, and track failed login attempts
• File Access and Modifications: Track when users create, edit, download, move, or delete files
• File and Folder Sharing: Monitor when users share content, with whom, and what permissions they grant
• User Sessions: Keep records of active sessions and authentication events
• Permission Changes: Log when sharing permissions are modified or revoked

Prerequisites and Dependencies

Before configuring user activity logging, ensure your environment meets the following requirements:

• Nextcloud Installation: A working Nextcloud instance (version 20 or later recommended)
• Shell Access: SSH or direct terminal access to your server
• Sudo Privileges: Administrative rights to execute commands as root or www-data
• Web Server: Apache2 with mod_fcgid (or nginx with PHP-FPM—adjust restart commands accordingly)
• OCC Access: Ability to run Nextcloud's command-line tool (occ)

The admin_audit app is included in Nextcloud by default, but may need to be installed or reinstalled to ensure a clean configuration state.

Step-by-Step Configuration Guide

Step 1: Reinstall the Admin_Audit App

To ensure a clean slate for your user activity logging setup, first remove and then reinstall the admin_audit app. This clears any previous configuration that might interfere:

sudo -u www-data php /opt/nextcloud/occ app:remove admin_audit
sudo -u www-data php /opt/nextcloud/occ app:install admin_audit

Replace /opt/nextcloud with your actual Nextcloud installation path if it differs.

Step 2: Configure a Dedicated User Activity Log File

By default, the admin_audit app writes to the main Nextcloud log. For better organization and easier analysis of user activities, configure a dedicated log file:

sudo -u www-data php /opt/nextcloud/occ config:app:set admin_audit logfile --value="/var/log/nextcloud_audit.log"

This command directs all user activity logs to /var/log/nextcloud_audit.log, keeping them separate from system errors and warnings.

Step 3: Enable User Activity Tracking Categories

Configure which types of user activities should be logged. The following commands enable tracking for filesystem operations, file sharing, and user authentication:

sudo -u www-data php /opt/nextcloud/occ config:app:set admin_audit filesystem --value="true"
sudo -u www-data php /opt/nextcloud/occ config:app:set admin_audit sharing --value="true"
sudo -u www-data php /opt/nextcloud/occ config:app:set admin_audit auth --value="true"

Each command enables a specific category of user activity tracking:

• filesystem: Logs when users create, read, update, delete, or move files and folders
• sharing: Logs when users share files, modify sharing permissions, or remove shares
• auth: Logs user login attempts (successful and failed), logouts, and session events

Step 4: Set the System Log Level (Required)

Important: You must set the Nextcloud log level to 1 (Info) or lower for user activity logging to work. The admin_audit app writes events at the Info level, so if your log level is set to 2 (Warning) or higher, no user activity will be recorded:

sudo -u www-data php /opt/nextcloud/occ config:system:set loglevel --value=1

Log level reference: 0 = Debug, 1 = Info (required for user activity logging), 2 = Warning, 3 = Error, 4 = Fatal.

Step 5: Create and Secure the Log File

Create the user activity log file with appropriate ownership and permissions:

sudo touch /var/log/nextcloud_audit.log
sudo chown www-data:www-data /var/log/nextcloud_audit.log
sudo chmod 640 /var/log/nextcloud_audit.log

The 640 permission ensures that only the web server user (www-data) can write to the file, and only www-data and root can read it. This protects sensitive user activity information from unauthorized access.

Step 6: Configure Log Rotation

Without log rotation, your user activity log will grow indefinitely and eventually consume all available disk space. Create a logrotate configuration to manage log file size:

sudo nano /etc/logrotate.d/nextcloud

Add the following configuration:

/var/log/nextcloud*.log {
    su www-data www-data
    monthly
    rotate 12
    compress
    delaycompress
    missingok
    notifempty
    create 640 www-data www-data
    sharedscripts
    postrotate
        /usr/bin/systemctl reload apache2 > /dev/null 2>&1 || true
    endscript
}

This configuration:

• Rotates logs monthly and keeps 12 months of user activity history
• Compresses old log files to save disk space
• Creates new log files with correct ownership and permissions
• Reloads Apache2 after rotation to ensure proper file handle management

PHP-FPM Users: If you are using PHP-FPM instead of mod_fcgid, add a line to restart your PHP-FPM service in the postrotate script:

postrotate
    /usr/bin/systemctl reload apache2 > /dev/null 2>&1 || true
    /usr/bin/systemctl reload php8.2-fpm > /dev/null 2>&1 || true
endscript

Adjust the PHP version number (php8.2-fpm) to match your installed version.

Step 7: Test the Logrotate Configuration

Verify that your logrotate configuration is valid before waiting for the next rotation cycle:

sudo logrotate -d /etc/logrotate.d/nextcloud

The -d flag runs logrotate in debug mode, showing what would happen without actually rotating the logs. Look for any error messages in the output.

Step 8: Restart the Admin_Audit App and Web Server

To apply all changes and start logging user activity, disable and re-enable the admin_audit app, then restart your web server:

sudo -u www-data php /opt/nextcloud/occ app:disable admin_audit
sudo -u www-data php /opt/nextcloud/occ app:enable admin_audit
systemctl restart apache2

PHP-FPM Users: Also restart your PHP-FPM service:

systemctl restart php8.2-fpm

Verifying Your User Activity Logging Setup

After completing the configuration, verify that user activity logging is working correctly.

Check App Status

Confirm that the admin_audit app is enabled:

sudo -u www-data php /opt/nextcloud/occ app:list | grep admin_audit

You should see admin_audit listed under enabled apps.

Verify Configuration Settings

Review the current user activity logging configuration:

sudo -u www-data php /opt/nextcloud/occ config:app:get admin_audit logfile
sudo -u www-data php /opt/nextcloud/occ config:app:get admin_audit auth
sudo -u www-data php /opt/nextcloud/occ config:app:get admin_audit filesystem
sudo -u www-data php /opt/nextcloud/occ config:app:get admin_audit sharing

Each command should return the expected value (the log path or "true").

Generate Test User Activity

Perform some actions in Nextcloud to generate log entries:

1. Log out and log back in to your Nextcloud account
2. Upload a test file
3. Share a file with another user or via public link
4. Delete the test file

Review the User Activity Log

Check that user activities are being recorded in the log file:

sudo tail -f /var/log/nextcloud_audit.log

You should see JSON-formatted log entries corresponding to your test actions. Each entry includes timestamps, user information, IP addresses, and activity details.

Troubleshooting Common Issues

Log File Not Being Created

If the user activity log file is not being created or remains empty:

• Check permissions: Ensure the /var/log/ directory is writable by www-data, or create the file manually with correct ownership
• Verify the path: Confirm the logfile path in the configuration matches the file you created
• Check SELinux/AppArmor: On systems with mandatory access control, you may need to add exceptions for the new log file location

# Check if SELinux is blocking writes
sudo ausearch -m avc -ts recent | grep nextcloud

# For AppArmor, check the syslog for DENIED entries
sudo grep -i apparmor /var/log/syslog | grep nextcloud

Admin_Audit App Not Appearing

If the admin_audit app fails to install or does not appear in your apps list:

• Check Nextcloud version: Ensure your Nextcloud version supports the admin_audit app
• Clear cache: Run sudo -u www-data php /opt/nextcloud/occ maintenance:repair
• Check app store connectivity: Verify your server can reach the Nextcloud app store

Permission Errors When Running OCC Commands

If you encounter permission errors:

• Always run occ commands as the web server user: sudo -u www-data php ...
• Ensure the Nextcloud directory has correct ownership: sudo chown -R www-data:www-data /opt/nextcloud
• Check that PHP CLI is using the correct configuration

User Activities Not Appearing in Log

If you perform actions but no log entries appear:

• Check log level (most common issue): The log level must be set to 1 (Info) or 0 (Debug). Run sudo -u www-data php /opt/nextcloud/occ config:system:get loglevel to verify. If it returns 2 or higher, user activities will not be logged
• Restart services: Ensure you have restarted Apache2 (and PHP-FPM if applicable) after configuration changes
• Disable and re-enable: Toggle the admin_audit app off and on again
• Check file permissions: Verify the log file is writable by www-data

Understanding User Activity Log Output

The user activity log writes entries in JSON format, making them easy to parse programmatically. Here is an example of a typical file deletion event from the trash bin:

{
  "reqId": "AbCdEfG1h2IjKlMn3oPq",
  "level": 1,
  "time": "Nov 27 19:52:23",
  "remoteAddr": "192.168.1.100",
  "user": "johndoe",
  "app": "admin_audit",
  "method": "DELETE",
  "url": "/remote.php/dav/trashbin/johndoe/trash/Workspace%20(1).d1764269506",
  "message": "File \"/files_trashbin/files//Workspace (1).d1764269506\" deleted from trash bin.",
  "userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/138.0.0.0 Safari/537.36",
  "version": "32.0.2.2",
  "data": {
    "app": "admin_audit"
  }
}

Key fields include:

• reqId: Unique request identifier for correlating related log entries
• time: Timestamp showing when the user activity occurred
• remoteAddr: IP address of the user performing the action
• user: Username of the person performing the action
• method: HTTP method used (GET, POST, DELETE, PUT, etc.)
• url: The endpoint or resource the user accessed
• message: Human-readable description of the user activity
• userAgent: Browser and operating system information of the client
• version: Nextcloud version running on the server

Comparison: Detailed User Activity Logging vs. Standard Nextcloud Logging

Feature	User Activity Logging (admin_audit)	Standard nextcloud.log
Track User Logins	Detailed (IP, time, success/fail)	Basic
Track File Access	Yes (who, what, when)	Errors Only
Track File Sharing	Yes	No
Dedicated Log File	Configurable	Fixed Location
JSON Format	Yes	Yes
Monitor User Behavior	Yes	Limited
Track User IP Addresses	Yes	Yes

Conclusion

Enabling detailed user activity logging in Nextcloud provides essential visibility into what users are doing on your self-hosted cloud platform. By following this guide, you have configured a dedicated log file that captures user logins, file access, and sharing activities—all with proper log rotation to manage disk space.

This setup forms the foundation for security monitoring, incident investigation, and understanding how your Nextcloud instance is being used. The JSON-formatted logs can be easily integrated with log analysis tools, making it straightforward to search for specific user activities, identify unusual behavior, and maintain oversight of your platform.

Remember to periodically review your user activity logs and adjust the configuration as your monitoring needs evolve. With proper logging in place, you maintain the visibility necessary to operate a secure and well-managed Nextcloud instance.