NeQter Labs How to Guides

Duo Log Sync – Linux Setup Guide

Step 1: Verify prerequisites

Before getting started, confirm the following requirements are met on the target Linux device:

• Python 3.8+
• Pip3 (Python package manager)
• Root (sudo) access
• Internet access to Duo API
• NeQter is reachable on port 514 (UDP)

Recommended: Linux Ubuntu Server 20.04 / 22.04. Although this is optional, the documentation below uses an Ubuntu 22 Server as a reference, exact commands and/or process may differ depending on distribution.

Step 2: Install or upgrade Python & Pip

If Python is not already installed on the Linux device, use the following commands to install it. You may be prompted to use a different command if you are faced with the error “This application is externally managed”.

sudo apt update
sudo apt install -y python3 python3-pip git

Verify installation:

python3 --version
pip3 --version

NOTE: If pip gives an “externally managed environment” message you can safely use the --break-system-packages flag when installing packages manually.

Step 3: Install required Python packages

1. Run the following to install the packages DuoLogSync depends on:

sudo python3 -m pip install --break-system-packages cerberus requests pyyaml

NOTE: Only add --break-system-packages if pip gives an “externally managed environment” message.

2. Verify successful installs:

python3 -m pip show cerberus pyyaml requests

After this command you should see three separate package descriptions, one for each package.

Step 4: Clone DuoLogSync

You can find the correct link in the Duo GitHub repo under the Code dropdown. There should be an HTTPS link you can copy and paste into your terminal.

cd /opt
sudo git clone https://github.com/duosecurity/duologsync.git
sudo chown -R root:root duologsync

This creates the directory /opt/duologsync/.

Step 5: Create the checkpoint directory

This directory stores DuoLogSync’s offset data so it knows where it left off between runs.

sudo mkdir -p /opt/duologsync/checkpoint
sudo chown root:root /opt/duologsync/checkpoint
sudo chmod 755 /opt/duologsync/checkpoint

Step 6: Create and set permissions for the local log file

sudo touch /tmp/duologsync.log
sudo chmod 666 /tmp/duologsync.log

Step 7: Configure the log sync

Copy and edit the example configuration file:

cd /opt/duologsync
sudo cp example_config.yml config.yml
sudo nano config.yml

Important

The configuration file can only contain single quotes (' '). The example uses double quotes (" ") which is incorrect and will produce syntax errors. Below is an example configuration. Replace the placeholder values with your actual Duo API credentials and NeQter’s IP address.

duo:
  ikey: 'YOUR_INTEGRATION_KEY'
  skey: 'YOUR_SECRET_KEY'
  host: 'api-XXXXXXXX.duosecurity.com'
  offset: 0
  checkpoint_file: '/opt/duo_log_sync/checkpoint'

output:
  type: 'syslog'
  syslog:
    address: '<NeQter_IP>'
    port: 514
    protocol: 'udp'
    format: 'json'

logging:
  file: '/tmp/duo_log_sync.log'
  level: 'info'

Step 8: Test the configuration manually

Run DuoLogSync manually first to make sure everything is working:

/usr/local/bin/duologsync /opt/duologsync/config.yml

If successful, you’ll see output similar to:

Starting Duo Log Sync
Fetching logs from offset: 0
Fetched X events
Shutting down gracefully

Make sure to check logs for errors via commands below:

tail -f /tmp/duologsync.log

Check checkpoint file:

ls -l /opt/duologsync/checkpoint/
cat /opt/duologsync/checkpoint/activity_checkpoint_data.txt

Step 9: Configure Duo Admin API permissions

In the Duo Admin Panel, go to Applications → Admin API → Permissions and ensure the following are enabled:

• Read information
• Read log
• Read authentication log
• Read Telemetry / TrustMonitor (if required)

NOTE: If you see a 40301 Access Forbidden error then your API key lacks permissions. Edit the Duo application and re-enable Read Logs.

Step 10: Create a systemd service for continuous sync

Create a service file:

sudo nano /etc/systemd/system/duologsync.service

Add the following contents:

[Unit]
Description=Duo Log Sync Service
After=network.target

[Service]
ExecStart=/usr/local/bin/duologsync /opt/duologsync/config.yml
User=root
Restart=always
StandardOutput=file:/tmp/duologsync.log
StandardError=file:/tmp/duologsync.log

[Install]
WantedBy=multi-user.target

Step 11: Enable and start the service

sudo systemctl daemon-reload
sudo systemctl enable duologsync
sudo systemctl start duologsync
sudo systemctl status duologsync

Step 12: Verify logs

1. Check the local log:

tail -f /tmp/duologsync.log

2. Check checkpoint progress:

cat /opt/duologsync/checkpoint/activity_checkpoint_data.txt

3. Test syslog forwarding:

sudo tail -f /var/log/syslog | grep duo

4. Check your NeQter for incoming Duo events in discover page.

Troubleshooting

Optional: Cleanup or reinstall

To completely remove DuoLogSync run the following:

sudo systemctl stop duologsync
sudo rm -rf /opt/duologsync
sudo rm /etc/systemd/system/duologsync.service
sudo rm -f /tmp/duologsync.log

Then reinstall following instructions from Step 3 onwards.

Return to Input Configuration