Troubleshooting

Installation issues

Common installation errors:

ErrorSolution
"Connection refused"PostgreSQL not running or wrong port
"Authentication failed"Wrong database credentials
"Database does not exist"Create database first: createdb tirreno
"Permission denied"Grant permissions: GRANT ALL ON DATABASE tirreno TO tirreno_app
"PDO PostgreSQL driver"Install: apt install php-pgsql
"Config folder permission"chmod 755 config && chown www-data:www-data config
"Memory limit"Set memory_limit = 128M in php.ini
Invalid hostname (TN8001)The application was accessed using a hostname that doesn't match the configured allowed host(s). This is a security measure to prevent host header attacks. The user must access the application through the correct URL defined in the configuration.
Failed DB connect (TN8002)The application cannot establish a connection to the PostgreSQL database. This could be caused by incorrect database credentials, the database server being down, network issues, or misconfigured connection parameters in the config file.
Incomplete config (TN8003)The application's configuration file (config/local/config.local.ini) is missing required settings or environment variable overrides are not properly set. The application cannot start without complete configuration.

PHP version check:

tirreno requires PHP 8.0–8.3. Verify your PHP version:

# Check PHP CLI version
php -v

# Check PHP version used by web server
php -r "echo PHP_VERSION;"

# Check all required extensions
php -m | grep -E "pdo_pgsql|curl|json|mbstring"

If using multiple PHP versions, ensure Apache/Nginx uses the correct one:

# Check PHP module loaded by Apache
apachectl -M | grep php

# For PHP-FPM, check the socket path in your nginx/apache config
ls -la /run/php/

Sending data issues

Note: The API uses form-urlencoded format, not JSON.

Events not appearing in tirreno:

  1. Check API key: Ensure your API key matches the one in tirreno settings
  2. Verify endpoint: Confirm you're posting to /sensor/ (with trailing slash)
  3. Check Logbook: Look for failed requests in the Logbook page
  4. Test with curl: 
curl -v -X POST https://your-tirreno.com/sensor/ \
  -H "Api-Key: your-api-key" \
  -d "userName=test" \
  -d "ipAddress=1.2.3.4" \
  -d "url=/test" \
  -d "eventTime=2024-12-08 01:01:00.000" \
  -d "eventType=page_view"

Check response codes:

CodeMeaning
200Success
401Invalid or missing API key
400Missing required parameters
429Rate limited
500Server error

Logbook review

The Logbook shows all incoming API requests:

  1. Access: Navigate to Logbook in the left menu
  2. Columns:
  3. Filtering: Use the search box to filter by any column
  4. Chart: Shows request volume over time

What to look for:

Cronjob issues

Manual cron:

php /home/user/tirreno/index.php /cron

Common cron issues:

IssueSolution
Jobs not runningCheck system cron is enabled: systemctl enable cron
"No jobs to run"Normal if no jobs scheduled for current minute
Permission deniedEnsure www-data can read config files
Database errorsCheck config/local/config.local.ini is readable
________________________________________________________________________________