STINGAR Settings

STINGAR provides several configuration options to customize your deployment:

User Management - Add, update and delete STINGAR users
Environment Variables Settings - View and modify environment variables from the UI
System Updates - Configure and manage automatic system updates
stingar.env - Customizing your configuration (manual editing)
docker-compose.yml - Modifying the STINGAR features

Environment Variables Settings

The Environment Variables Settings page provides a user-friendly interface to view and modify environment variables that control STINGAR's behavior. This page allows you to configure settings without manually editing the stingar.env file.

Accessing the Settings Page

To access the Environment Variables Settings page:

Click Environment Variables in the Settings section of the left sidebar
The page will display all configurable environment variables organized into logical groups

Variable Groups

Environment variables are organized into the following groups:

Honeypot App Store Configuration

Variables that control the connection to the Honeypot App Store:

HP App Store Enabled (REMOTE_STORE_ENABLED) - Enable or disable connection to the HP App Store. When enabled, STINGAR will automatically attempt to connect your instance to the Store.
HP App Store API Key (REMOTE_STORE_API_KEY) - API key for authenticating with the HP App Store. This is automatically generated when you enable the store and register your instance.
HP App Store Base URL (REMOTE_STORE_BASE_URL) - The base URL for the HP App Store API (default: https://store.4warned.io)

Note: When you enable the HP App Store for the first time, STINGAR will automatically register your instance and receive an API key. This process happens in the background and does not require any user interaction.

Other Configuration

Additional system configuration variables including:

System configuration (API host, service URLs, healthcheck intervals)
UI settings (theme colors, default rows per page)
Security settings (session secret, passphrase, salt)
Logging configuration (Fluentd, Fluent Bit settings)
Docker settings (repository, credentials)
LDAP authentication settings
IDS Rules feed settings (auto-update interval, cache path, date range)
And more...

Editing Variables

To modify an environment variable:

Navigate to the Environment Variables Settings page
Find the variable you want to modify in its respective group
Edit the value in the input field or toggle the switch (for boolean values)
Changed fields will be highlighted to show they have unsaved modifications
Click Save Changes to apply your modifications
Click Reset to discard changes and revert to the original values

Variable Types

Different variable types use different input controls:

Boolean - Toggle switch (on/off)
String - Text input field
Email - Email input field with validation
URL - URL input field with validation
Number - Number input field

Sensitive Variables

Sensitive variables (such as API keys and passwords) are masked by default for security:

Values are displayed as asterisks (********)
Click the eye icon to show/hide the actual value
When editing, you can see the value you're typing

Security Note: Sensitive values are masked in the UI but are stored in plain text in the `stingar.env` file. Ensure proper file permissions are set on the `stingar.env` file.

Saving Changes

When you click Save Changes:

All modified variables are validated according to their type and format requirements
If validation passes, changes are written to the stingar.env file
Appropriate actions are triggered based on which variables changed:
Enabling HP App Store triggers automatic connection to the HP App Store
Changing API key reloads the remote store configuration
Changing base URL updates the remote store configuration
A success message will appear confirming the changes were saved
The page will refresh to show the updated values

If validation fails, error messages will be displayed indicating which variables have issues and what needs to be corrected.

Validation

The Settings page validates all variable values before saving:

Required Fields - Some variables require a value and cannot be empty
Format Validation - Email addresses, URLs, and other formatted fields are validated
Type Validation - Boolean values must be true/false, numbers must be valid numbers
Range Validation - Numbers may have minimum/maximum values (e.g., ports must be 1-65535)
Pattern Validation - Some variables must match specific patterns

Validation errors are displayed inline with each field, making it easy to identify and fix issues.

Action Triggers

Changing certain variables triggers automatic actions:

Enabling HP App Store (REMOTE_STORE_ENABLED changed to true):
Automatically triggers connection with the HP App Store
Generates and stores an API key
Enables access to browse, download and request honeypots
Changing API Key (REMOTE_STORE_API_KEY):
Reloads the remote store configuration
Validates the API key format
Changing Base URL (REMOTE_STORE_BASE_URL):
Updates the remote store configuration
Validates the URL format
Changing Instance Information (INSTITUTION_NAME, CONTACT_EMAIL):
Updates instance identification String in UI Banner

File Persistence

All changes are persisted to the stingar.env file:

Changes are written immediately when you click Save Changes
The file is located at stingar.env
File permissions are automatically set to 664 (rw-rw-r--) for Docker compatibility
Changes survive container restarts
The file format is preserved (comments, grouping, etc.)

Note: Some variables may require a service restart to take effect. The Settings page will indicate if a restart is needed for specific changes.

Automatic File Updates During System Updates

When STINGAR applies system updates, two files are automatically updated:

stingar.env Updates

The stingar.env file may be updated during system updates if new environment variables are introduced or existing variables need modification. These updates are applied automatically and preserve your existing configuration values where possible.

docker-compose.yml Updates

The docker-compose.yml file (or docker-compose-v2.3.yml) is automatically updated during system updates to reflect new Docker image tags:

Before Update: A timestamped backup is created automatically (stored in ./storage/db/update-state/)
During Update: Image tags for all STINGAR services are updated to the new version
Preservation: All other configuration (volumes, environment variables, networks, etc.) is preserved
After Update: The updated compose file ensures containers use the correct images after server restarts

Important: The automatic update of `docker-compose.yml` ensures that updates persist across server restarts. If you restart your server after an update, containers will automatically use the updated image versions specified in the compose file.

Backup Files

Before updating docker-compose.yml, STINGAR creates a backup:

Backup Location: ./storage/db/update-state/docker-compose-v2.3.yml.backup.TIMESTAMP
Backup Format: Timestamped backups (e.g., docker-compose-v2.3.yml.backup.20260109_193500)
Retention: Backups are retained indefinitely (you may manually clean them up if needed)
Recovery: If an update fails, the system automatically restores from the most recent backup

For detailed recovery procedures, see the Manual Recovery Procedures section below.

Troubleshooting

Changes Not Saving

Ensure you have proper file permissions on stingar.env
Check that the file is not read-only
Verify Docker volume mount is configured correctly

Validation Errors

Review the error messages displayed with each field
Ensure values match the required format (e.g., email addresses, URLs)
Check that required fields are not empty
Verify number ranges are within allowed limits

HP App Store Not Connecting

Verify REMOTE_STORE_ENABLED is set to true
Check that REMOTE_STORE_API_KEY is present and valid
Ensure REMOTE_STORE_BASE_URL is correct
Check network connectivity to the HP App Store
Review stingarapi container logs (docker-compose logs -f stingarapi) for connection errors

System Updates

STINGAR includes an automated update system that can check for new versions and apply updates with minimal downtime. The update system runs entirely within the STINGAR container and manages Docker image downloads and container restarts automatically.

Accessing the Update Settings

To access the System Updates page:

Click Settings in the left sidebar
Select the System Updates tab section
The page displays current version information, update status, and configuration options

Version Information

The Update Settings page displays:

Current Version - The currently installed STINGAR version (e.g., v2.3)
Latest Version - The latest available version (e.g., v2.3.1)
Update Available - Indicates if a newer version is available for installation

Update Modes

STINGAR supports two update modes:

Manual Mode (Default)

System checks for updates automatically in the background
When an update is available, you receive a notification
You must manually approve and trigger the update installation
Provides full control over when updates are applied
Recommended for production environments where you want to review updates before applying

Automatic Mode

System checks for updates automatically in the background
When an update is available AND within the update window, it is automatically applied
No user interaction required
Updates are applied during the configured update window only
Useful for environments where you want hands-off updates

Important: Even in automatic mode, updates are only applied during the configured update window. This ensures updates happen during low-usage periods.

Update Window

The update window defines when updates can be automatically applied. This prevents updates from occurring during peak usage hours.

Update Window Start - Start time for the update window (default: 00:00 / midnight)
Update Window End - End time for the update window (default: 06:00 / 6 AM)
Updates can only be applied (manually or automatically) during this time window
The window can span midnight (e.g., 22:00 - 06:00)

Example: If your update window is set to 00:00 - 06:00, updates can only be applied between midnight and 6 AM. If you try to apply an update at 2 PM, you'll see a message indicating you're outside the update window.

Update Service Configuration

Enable Update Service

When enabled, STINGAR will:

Periodically check for new versions (default: every 3 hours)
Automatically download new Docker images when available (if within update window)
Display update notifications when new versions are available

When disabled:

No automatic version checks
No automatic image downloads
Manual updates can still be triggered from the Settings page

Check Interval

The frequency at which STINGAR checks for new versions:

Default: 10800 seconds (3 hours)
Configurable via environment variable UPDATE_CHECK_INTERVAL
Checks happen in the background and do not impact system performance

Checking for Updates

To manually check if a new version is available:

Navigate to Settings > System Updates
Click the Check for Updates button
The system will query for the latest version
If an update is available, you'll see:
The latest version number
Whether you're currently within the update window
An Install Update button (if within window)

Applying Updates

When an update is available and you're within the update window:

Click Install Update button
A progress dialog will appear showing the update workflow steps:
Validating - Pre-update checks (disk space, service health)
Pulling - Downloading new Docker images
Updating Compose - Creating backup and updating docker-compose.yml with new image tags
Restarting - Restarting containers with new images
Waiting - Waiting for services to become ready
Completing - Finalizing the update

Update Workflow Process

The update process follows these steps:

Pre-Update Validation:
Checks available disk space (minimum 2GB required)
Verifies current service health
Ensures all required Docker images are available
Image Download:
Downloads new Docker images directly from Docker Hub
Images are pulled by tag (e.g., 4warned/stingar-api:v2.3.1)
Progress is shown for each image being downloaded
Docker Compose File Backup:
Creates a timestamped backup of the current docker-compose.yml file
Backup is stored in /srv/db/update-state/ (persisted on host at ./storage/db/update-state/)
Backup filename format: docker-compose-v2.3.yml.backup.YYYYMMDD_HHMMSS
This ensures updates persist across server restarts
Docker Compose File Update:
Updates image tags in docker-compose.yml to reflect new version
Preserves all other configuration (volumes, environment variables, etc.)
Ensures containers use correct images after server restart
Image Verification:
Verifies all required images were successfully downloaded
Lists any missing images if verification fails
Container Restart:
Automatically discovers STINGAR containers
Restarts each container individually to use new images
Preserves all volumes and data
Post-Update Validation:
Waits for services to become ready (up to 2 minutes)
Performs health checks to ensure services are operational
Updates version state file
Automatic Rollback (if update fails):
If any step fails, the system automatically attempts rollback
Restores docker-compose.yml from backup file
Restarts containers with previous version images
Restores previous version state

Note: The update process preserves all your data, configurations, and honeypot deployments. Volumes are not affected by container restarts.

Update Settings

Update Mode

Manual - Requires user approval before applying updates
Automatic - Automatically applies updates during the update window

Update Window Configuration

Update Window Start - Time when updates can begin (24-hour format, e.g., 00:00)
Update Window End - Time when updates must complete (24-hour format, e.g., 06:00)

Service Options

Enable Update Service - Enable/disable automatic update checking and image downloading
Cleanup Old Images - Automatically remove old Docker images after successful updates (future feature)

Update Status Information

The Update Settings page displays current status:

Service Enabled - Whether the update service is active
Remote Store - Connection status to the remote version store
Check Interval - How often the system checks for updates
Update Window - Current update window configuration
Within Window - Visual indicator showing if current time is within the update window

Update Progress Monitoring

When an update is in progress:

A progress dialog shows each step of the update workflow
Each step displays:
Status (Validating, Pulling, Updating Compose, Restarting, etc.)
Description of what's happening
Timestamp of when the step occurred
Error messages if a step fails
The dialog updates in real-time as the update progresses
You can close the dialog and check status later using the job ID

Note: The "Updating Compose" step shows when the system is creating a backup of `docker-compose.yml` and updating it with new image tags. This ensures updates persist across server restarts.

Backup and Recovery

Automatic Backup Creation

Before updating the docker-compose.yml file, STINGAR automatically creates a timestamped backup:

Backup Location: /srv/db/update-state/ inside the container
Host Location: ./storage/db/update-state/ on your host system
Backup Filename Format: docker-compose-v2.3.yml.backup.YYYYMMDD_HHMMSS
Example: docker-compose-v2.3.yml.backup.20260109_193500

Backups are created automatically before each update attempt and are retained indefinitely (you may manually clean them up if needed).

What Gets Backed Up

The backup includes the complete docker-compose.yml file with:

All service definitions
Image tags (before update)
Volume mounts
Environment variable configurations
Network settings
All other docker-compose configuration

Verifying Backups

To verify backups exist on your system:

# List all backup files
ls -la ./storage/db/update-state/docker-compose-v2.3.yml.backup.*

# View the most recent backup
ls -lt ./storage/db/update-state/docker-compose-v2.3.yml.backup.* | head -1

Automatic Rollback

If an update fails at any point, STINGAR automatically attempts to rollback:

Restores docker-compose.yml from the most recent backup file
Containers are restarted with previous version images (still cached locally)
Version state is restored to previous version
System returns to the state before the update attempt
Error details are logged for troubleshooting

Rollback occurs automatically if:

Image download fails
Docker compose file update fails
Container restart fails
Health checks fail after restart
Any unexpected error occurs during update

Note: Automatic rollback uses the most recent backup file (sorted by modification time) to restore the `docker-compose.yml` file to its pre-update state.

Requirements

For the update system to function properly:

Docker Socket Access - The stingarapi container must have access to the Docker socket (/var/run/docker.sock) defined in the docker-compose.yml file
Docker Compose File Mount - The docker-compose file must be mounted into the stingarapi container (e.g., ./docker-compose-v2.3.yml:/app/docker-compose-v2.3.yml:rw) to enable automatic updates
Remote Store Connection - HP App Store must be enabled and connected (REMOTE_STORE_ENABLED=true)
API Key - Valid API key for authenticating with the remote store
Network Access - Ability to connect to Docker Hub to pull images
Disk Space - Minimum 2GB free disk space for new images

Docker Compose File Detection

When multiple docker-compose files exist in your directory (e.g., docker-compose.yml and docker-compose-v2.3.yml), STINGAR automatically detects which file was used to start the containers:

Automatic Detection - The system checks which compose file is mounted into the container and uses that file for backups and updates
Mount Requirement - The compose file must be mounted into the container (this is already configured in docker-compose-v2.3.yml)
Environment Variable - You can set COMPOSE_FILE in stingar.env to specify the compose file name (defaults to docker-compose.yml), but mounted files take precedence

Note: If you use a custom compose file, ensure it's mounted into the `stingarapi` container with read-write permissions (`:rw`) to enable automatic updates. The mount should be similar to: `./your-compose-file.yml:/app/your-compose-file.yml:rw`

Troubleshooting

Update Not Available

Verify you're within the update window
Check that Remote Store is connected (status shown on Update Settings page)
Ensure API key is valid and configured
Check stingar-api container logs for connection errors

Update Fails During Image Download

Verify network connectivity to Docker Hub
Check available disk space (minimum 2GB required, plus ~1GB per image)
Review stingar-api container logs for specific error messages
Ensure Docker socket is properly mounted
System will automatically attempt rollback if download fails

Update Fails During Docker Compose File Update

Check that the compose file is mounted and writable
Verify backup was created successfully (check ./storage/db/update-state/)
Review stingar-api container logs for file permission errors
System will automatically attempt rollback if compose file update fails

Update Fails During Container Restart

Check Docker socket permissions
Verify Docker CLI is installed in the container
Review container logs for restart errors
System will automatically attempt rollback

Service Health Check Fails

Wait a few minutes and try again (services may need time to start)
Check stingar-api container logs for service errors
Verify all required services are running
System will automatically rollback if health checks fail

Update Window Issues

Updates can only be applied during the configured window
If outside the window, you'll see a message indicating when updates can be applied
You can adjust the update window in Settings if needed
Window can span midnight (e.g., 22:00 - 06:00)

Manual Recovery Procedures

If automatic rollback fails or you need to manually recover to a previous version, follow these steps:

Step 1: Verify Backup Files Exist

Check that backup files are available:

# Navigate to your STINGAR directory
cd /path/to/stingar-development

# List all backup files
ls -la ./storage/db/update-state/docker-compose-v2.3.yml.backup.*

# View backup file details (most recent first)
ls -lt ./storage/db/update-state/docker-compose-v2.3.yml.backup.* | head -5

If no backup files exist, you may need to manually edit docker-compose-v2.3.yml to restore previous image tags.

Step 2: Identify the Backup to Restore

Backup files are named with timestamps. To find the backup from before your update:

# List backups with timestamps
ls -lt ./storage/db/update-state/docker-compose-v2.3.yml.backup.* | head -10

# Example output:
# docker-compose-v2.3.yml.backup.20260109_193500  (most recent)
# docker-compose-v2.3.yml.backup.20260109_180000  (earlier)
# docker-compose-v2.3.yml.backup.20260108_120000  (even earlier)

Choose the backup file from before your failed update attempt.

Step 3: Stop Running Containers

Stop all STINGAR containers:

# Stop containers gracefully
docker-compose -f docker-compose-v2.3.yml down

# Or stop specific containers
docker-compose -f docker-compose-v2.3.yml stop stingarapi stingarui elasticsearch kibana fluentd langstroth

Step 4: Restore Docker Compose File

Restore the backup file:

# Copy backup to restore docker-compose file
# Replace TIMESTAMP with your backup timestamp
cp ./storage/db/update-state/docker-compose-v2.3.yml.backup.TIMESTAMP ./docker-compose-v2.3.yml

# Example:
# cp ./storage/db/update-state/docker-compose-v2.3.yml.backup.20260109_193500 ./docker-compose-v2.3.yml

# Verify the file was restored correctly
cat ./docker-compose-v2.3.yml | grep "image:"

Verify that the image tags in the restored file match the previous version you want to use.

Step 5: Verify Previous Version Images Are Available

Check that Docker images for the previous version are still available locally:

# List Docker images
docker images | grep "4warned/stingar"

# Example output:
# 4warned/stingar-api    v2.3.1     abc123def456    2 hours ago    500MB
# 4warned/stingar-api    v2.3       xyz789uvw012    1 week ago     480MB

If the previous version images are not available, you'll need to pull them:

# Pull previous version images
docker pull 4warned/stingar-api:v2.3
docker pull 4warned/stingar-ui:v2.3
docker pull 4warned/elasticsearch:v2.3
docker pull 4warned/kibana:v2.3
docker pull 4warned/fluentd:v2.3
docker pull 4warned/langstroth:v2.3

Step 6: Restart Containers

Start containers with the restored compose file:

# Start containers
docker-compose -f docker-compose-v2.3.yml up -d

# Monitor startup
docker-compose -f docker-compose-v2.3.yml logs -f

Step 7: Verify Services Are Running

Check that all services started successfully:

# Check container status
docker-compose -f docker-compose-v2.3.yml ps

# Check service health
curl http://localhost:8000/api/v2

# Check UI is accessible
curl http://localhost:3000

Step 8: Verify Version State

Check the version state file to ensure it reflects the restored version:

# View version state (inside container)
docker exec stingar_stingarapi_1 cat /srv/db/update-state/version.json

# Or on host
cat ./storage/db/update-state/version.json

If the version state file shows the wrong version, you may need to manually edit it or wait for the next automatic version check.

Alternative: Quick Recovery Using Docker Commands

If you know the exact previous version and images are cached, you can quickly restore:

# 1. Stop containers
docker-compose -f docker-compose-v2.3.yml down

# 2. Restore compose file from backup
cp ./storage/db/update-state/docker-compose-v2.3.yml.backup.LATEST_TIMESTAMP ./docker-compose-v2.3.yml

# 3. Restart containers
docker-compose -f docker-compose-v2.3.yml up -d

# 4. Verify
docker-compose -f docker-compose-v2.3.yml ps

Recovery Checklist

Use this checklist when recovering from a failed update:

[ ] Backup files exist in ./storage/db/update-state/
[ ] Identified correct backup file (from before failed update)
[ ] Stopped all STINGAR containers
[ ] Restored docker-compose-v2.3.yml from backup
[ ] Verified image tags in restored compose file
[ ] Confirmed previous version images are available locally
[ ] Restarted containers successfully
[ ] Verified all services are running and healthy
[ ] Tested UI and API access
[ ] Reviewed container logs for errors

Preventing Future Issues

To minimize the need for manual recovery:

Monitor Update Progress - Watch the update progress dialog to catch issues early
Review Logs - Check container logs after updates for warnings or errors
Test Updates - If possible, test updates in a staging environment first
Maintain Backups - Keep regular backups of your data (see Backup & Restore)
Verify Disk Space - Ensure adequate disk space before updates (minimum 2GB + ~1GB per image)
Check Network - Verify connectivity to Docker Hub before updates
Use Manual Mode - In production, consider using manual mode to review updates before applying

Best Practices

Schedule Updates During Low Usage - Configure update window for off-peak hours
Monitor Update Progress - Watch the progress dialog to ensure successful completion
Review Update Logs - Check stingar-api container logs after updates for any warnings or errors
Verify Backup Creation - After updates, verify backup files exist in ./storage/db/update-state/
Test in Staging First - If possible, test updates in a staging environment before production
Keep Backups - Always maintain backups of your data (see Backup & Restore)
Review Backup Files - Periodically check that backup files are being created successfully
Manual Mode for Production - Use manual mode in production to review updates before applying
Monitor Disk Space - Ensure adequate free disk space (minimum 2GB + ~1GB per Docker image)
Clean Up Old Backups - Periodically remove old backup files if disk space is limited (keep at least the most recent 5-10 backups)

STINGAR Settings

Environment Variables Settings

Accessing the Settings Page

Variable Groups

Honeypot App Store Configuration

Other Configuration

Editing Variables

Variable Types

Sensitive Variables

Saving Changes

Validation

Action Triggers

File Persistence

Automatic File Updates During System Updates

stingar.env Updates

docker-compose.yml Updates

Backup Files

Troubleshooting

Changes Not Saving

Validation Errors

HP App Store Not Connecting

System Updates

Accessing the Update Settings

Version Information

Update Modes

Manual Mode (Default)

Automatic Mode

Update Window

Update Service Configuration

Enable Update Service

Check Interval

Checking for Updates

Applying Updates

Update Workflow Process

Update Settings

Update Mode

Update Window Configuration

Service Options

Update Status Information

Update Progress Monitoring

Backup and Recovery

Automatic Backup Creation

What Gets Backed Up

Verifying Backups

Automatic Rollback

Requirements

Docker Compose File Detection

Troubleshooting

Update Not Available

Update Fails During Image Download

Update Fails During Docker Compose File Update

Update Fails During Container Restart

Service Health Check Fails

Update Window Issues

Manual Recovery Procedures

Step 1: Verify Backup Files Exist

Step 2: Identify the Backup to Restore

Step 3: Stop Running Containers

Step 4: Restore Docker Compose File

Step 5: Verify Previous Version Images Are Available

Step 6: Restart Containers

Step 7: Verify Services Are Running

Step 8: Verify Version State

Alternative: Quick Recovery Using Docker Commands

Recovery Checklist

Preventing Future Issues

Best Practices

Related Documentation