F5 BIG-IP iRules

tmsh list sys dns

tmsh modify sys dns name-servers add { 8.8.8.8 1.1.1.1 }
tmsh save sys config

Installation

# Download the package
curl -O https://docs.centinelanalytica.com/downloads/centinel-f5-irules.tar.gz

# Extract files
tar -xzf centinel-f5-irules.tar.gz

# You should see:
# - Centinel.tcl
# - Centinel-SSL-Helper.tcl
# - README.md

# Upload files to /var/tmp/ first
tmsh create ltm rule Centinel from-file /var/tmp/Centinel.tcl
tmsh create ltm rule Centinel-SSL-Helper from-file /var/tmp/Centinel-SSL-Helper.tcl

# Replace with your actual API key
set static::CENTINEL_SECRET_KEY "sk_live_your_key_here"

tmsh edit ltm rule Centinel
# Update the key, then save and exit

tmsh create ltm virtual centinel_api_ssl_vs \
    destination 0.0.0.0:443 \
    ip-protocol tcp \
    mask 0.0.0.0 \
    profiles add { tcp http { context all } serverssl-insecure-compatible { context serverside } clientssl-insecure-compatible { context clientside } }
    source 0.0.0.0/0 \
    source-address-translation { type automap } \
    translate-address disabled \
    translate-port disabled

tmsh modify ltm virtual centinel_api_ssl_vs rules { Centinel-SSL-Helper }

tmsh modify ltm virtual your_application_vs rules { Centinel }

tmsh save sys config

tmsh list sys dns

sys dns {
    name-servers { 8.8.8.8 1.1.1.1 }
    search { example.com }
}

tmsh modify sys dns name-servers add { 8.8.8.8 1.1.1.1 }
tmsh save sys config

run /util dig validator.centinelanalytica.com

Advanced configuration

# Example: Exclude health checks and metrics
set static::CENTINEL_URI_REGEX_EXCLUSION {(?i)\.(avi|flv|mka|mkv|mov|mp4|mpeg|mpg|mp3|flac|ogg|ogm|opus|wav|webm|webp|bmp|gif|ico|jpeg|jpg|png|svg|svgz|swf|eot|otf|ttf|woff|woff2|css|less|js)$|^/health$|^/metrics$}

# Only protect paths starting with /api/ or /admin
set static::CENTINEL_URI_REGEX {^/(api|admin)/}

# Increase timeout to 300ms for slower networks
set static::CENTINEL_timeout 300

# Enable debug logging
set static::CENTINEL_LOG_REQUEST_HEADERS 1
set static::CENTINEL_LOG_RESPONSE_HEADERS 1
set static::CENTINEL_LOG_REQUEST_TIME 1

# Real-time log monitoring
tail -f /var/log/ltm | grep CENTINEL

# Search for errors
grep "CENTINEL ERROR" /var/log/ltm

set static::CENTINEL_LOG_PUBLISHER "/Common/remote_log_publisher"

Security decisions

The Centinel API returns one of four decisions:

Challenge flow (redirect decision)

When a redirect decision is returned:

1. F5 serves a base64-encoded HTML challenge page to the client
2. Browser executes JavaScript challenge
3. Challenge validation cookie is set
4. Client is redirected back to original URL
5. Subsequent request includes validation cookie
6. Centinel validates cookie and allows request

Configuration reference

Main iRule variables

Edit these in the Centinel iRule (lines 5-36):

API endpoint

The iRule connects to: https://validator.centinelanalytica.com/validate

This is hardcoded in the iRule.

DNS dependency: The iRule uses RESOLV::lookup to resolve the API hostname. This requires DNS servers configured in TMM (tmsh sys dns). See the DNS Configuration Required warning in Prerequisites.

Network requirements:

• DNS servers configured in TMM (not just shell /etc/resolv.conf)
• Outbound HTTPS (port 443) allowed from F5 device
• TLS 1.2+ support (handled by serverssl-insecure-compatible profile)

Troubleshooting

Systematic diagnosis

Before jumping to solutions, figure out what's actually failing:

Step 1: Confirm the symptom

What are you seeing?

Run these commands to gather data:

# Check if iRules are applied
tmsh list ltm virtual your_application_vs rules

# Check recent logs
tail -100 /var/log/ltm | grep -E "CENTINEL|error|Error"

# Test a request and watch logs
tail -f /var/log/ltm | grep CENTINEL &
curl -I https://your-application.com

Common symptoms:

• Browser shows redirect loop / ERR_TOO_MANY_REDIRECTS
• HTTP 555 errors in logs
• "Cannot resolve" errors in logs
• Requests timing out
• No logs appearing at all
• Requests work but don't show in Centinel dashboard

Step 2: Test each component

Work through this checklist:

A. Is the iRule executing at all?

# Check iRule statistics
tmsh show ltm rule Centinel

# Look for "Total Executions" > 0

• If Total Executions = 0: iRule not attached to virtual server, or virtual server not receiving traffic
• If Total Executions > 0: iRule is running, proceed to next test

B. Can the F5 shell reach the API?

# Test from F5 shell (uses /etc/resolv.conf, NOT TMM DNS)
curl -v --max-time 5 https://validator.centinelanalytica.com/validate \
  -H "X-Centinel-Secret-Key: your_secret_key"

• If this works: Shell networking is fine, problem is probably TMM-specific (DNS, virtual server, SIDEBAND)
• If this fails: Network/firewall issue affecting the entire F5 device

C. Is TMM DNS configured?

# Check TMM DNS configuration
tmsh list sys dns

• If no name-servers shown: DNS not configured—TMM can't resolve hostnames
• If name-servers present: DNS is configured, test if it works:

# Test DNS resolution using TMM
run /util dig validator.centinelanalytica.com

• If dig fails: DNS servers are configured but not reachable or not working
• If dig succeeds: DNS is working, problem is elsewhere

D. Does the API virtual server exist?

# Check if API virtual server exists and is configured correctly
tmsh list ltm virtual centinel_api_ssl_vs

• If "not found": Virtual server doesn't exist—create it (see Installation)
• If exists, check these fields:
  • destination 0.0.0.0:443
  • translate-address disabled
  • translate-port disabled
  • source-address-translation { type automap }

E. Is SSL-Helper attached to API virtual server?

# Check if SSL-Helper iRule is attached
tmsh list ltm virtual centinel_api_ssl_vs rules

• If no rules or wrong rule: Attach Centinel-SSL-Helper (see Installation Step 5)
• If Centinel-SSL-Helper present: SSL-Helper is attached correctly

F. Is the API key correct?

# Check the configured API key
tmsh list ltm rule Centinel | grep CENTINEL_SECRET_KEY

• If key looks wrong or is default: Update the key (see Installation Step 3)
• If key looks correct: Test it manually:

curl -v https://validator.centinelanalytica.com/validate \
  -H "X-Centinel-Secret-Key: sk_live_your_actual_key" \
  -H "X-Centinel-Client-IP: 1.2.3.4" \
  -H "X-Centinel-Request-URI: /test"

Should return JSON with "decision":"not_matched" or similar.

Step 3: Analyze the results

Based on your test results:

iRule compilation errors

Error: line X: syntax error

Solution: Make sure you copied the entire iRule file without truncation. Check for special characters or encoding issues.

# Validate iRule syntax before uploading
tmsh create ltm rule test_rule from-file /var/tmp/Centinel.tcl
tmsh delete ltm rule test_rule

API virtual server not working

Error: Unable to connect to Centinel API

Solution: Verify the API virtual server is configured correctly:

# Check virtual server status
tmsh show ltm virtual centinel_api_ssl_vs

# Test DNS resolution
tmsh run util dig validator.centinelanalytica.com

# Test HTTPS connectivity
tmsh run util curl https://validator.centinelanalytica.com/validate

SSL certificate errors

Error: SSL handshake failed

Solution: Use the serverssl-insecure-compatible profile (as shown in installation). This profile allows outbound HTTPS without client certificates.

If you need custom SSL validation:

# Create custom server SSL profile
tmsh create ltm profile server-ssl centinel-serverssl \
    defaults-from serverssl \
    server-name validator.centinelanalytica.com \
    ca-file /config/ssl/ssl.crt/ca-bundle.crt

High latency or timeouts

Symptom: Requests are slow or timing out

Solution:

1. Increase timeout:

   set static::CENTINEL_timeout 300

2. Check network path:

   # From F5, test API latency
   tmsh run util curl -w "@-" -o /dev/null -s \
     https://validator.centinelanalytica.com/validate \
     <<< "time_total: %{time_total}s"

3. Make sure no firewall blocking - Outbound HTTPS (port 443) must be allowed

No requests showing in dashboard

Symptom: F5 logs show API calls, but Centinel dashboard shows no activity

Solution:

1. Verify API key: Check that CENTINEL_SECRET_KEY is correct
2. Check API response: Enable debug logging to see API responses:

   set static::CENTINEL_LOG_RESPONSE_HEADERS 1

3. Confirm virtual server is receiving traffic:

   tmsh show ltm virtual your_application_vs

Redirect loop or too many redirects

Symptom: Browser shows ERR_TOO_MANY_REDIRECTS or "This page isn't working"

If you've confirmed this is a DNS issue, here's the typical error chain:

1. TMM DNS not configured → RESOLV::lookup fails
2. Can't resolve validator.centinelanalytica.com
3. SSL-Helper can't connect to API → HTTP 555 error
4. Fail-open allows the request through
5. Application redirects → loop continues

DNS-specific solution:

1. Check DNS configuration:

   tmsh list sys dns

2. Add DNS servers if missing:

   tmsh modify sys dns name-servers add { 8.8.8.8 1.1.1.1 }
   tmsh save sys config

3. Test DNS resolution:

   run /util dig validator.centinelanalytica.com

   You should see an ANSWER SECTION with IP addresses.

4. Verify logs show success:

   tail -f /var/log/ltm | grep CENTINEL

   Look for successful API responses instead of HTTP 555 errors.

HTTP 555 errors in logs

Symptom: Logs show API returned HTTP 555 or SIDEBAND connection failed

What it means: HTTP 555 isn't a standard status code. In F5, it indicates a SIDEBAND connection failure (the iRule couldn't connect to the API virtual server).

Why this happens: SIDEBAND connections fail when any part of the connection chain is broken:

• DNS can't resolve the hostname
• API virtual server doesn't exist or is misconfigured
• SSL-Helper iRule not attached to API virtual server
• Network/firewall blocking the connection
• Wrong virtual server name in CENTINEL_vs variable

Quick diagnostic steps:

1. Check DNS configuration:

   tmsh list sys dns

   If no name-servers shown, configure DNS (see "DNS resolution failures" section).

2. Verify API virtual server exists:

   tmsh list ltm virtual centinel_api_ssl_vs

3. Test network connectivity:

   curl -v https://validator.centinelanalytica.com/validate

4. Check firewall rules: Make sure outbound HTTPS (port 443) is allowed from the F5 device

5. Enable debug logging:

   set static::CENTINEL_LOG_REQUEST_HEADERS 1
   set static::CENTINEL_LOG_RESPONSE_HEADERS 1

Quick checklist:

• TMM DNS configured (tmsh list sys dns)
• API virtual server exists (centinel_api_ssl_vs)
• SSL-Helper iRule attached to API virtual server
• DNS resolves hostname (run /util dig validator.centinelanalytica.com)
• Outbound port 443 allowed
• API key is correct in CENTINEL_SECRET_KEY

DNS resolution failures

Error: cannot resolve validator.centinelanalytica.com in logs

Solution:

1. Configure TMM DNS servers:

   # Add public DNS servers
   tmsh modify sys dns name-servers add { 8.8.8.8 1.1.1.1 }
   tmsh save sys config

2. Verify configuration:

   tmsh list sys dns

   Expected:

   sys dns {
       name-servers { 8.8.8.8 1.1.1.1 }
   }

3. Test resolution:

   run /util dig validator.centinelanalytica.com

   Expected output should include:

   ;; ANSWER SECTION:
   validator.centinelanalytica.com. 300 IN A 13.248.169.98
   validator.centinelanalytica.com. 300 IN A 76.223.95.45

4. Verify iRule can now resolve:

   tail -f /var/log/ltm | grep CENTINEL

   You should no longer see DNS resolution errors.

Still having issues after DNS configuration?

If DNS is configured but you're still having problems, do advanced diagnostics:

1. Verify DNS is actually working in TMM

Test DNS resolution from within the iRule context:

# Enable detailed iRule logging
tmsh modify ltm rule Centinel
# Add this line temporarily after line 10:
# log local0. "DNS TEST: [RESOLV::lookup @validator.centinelanalytica.com]"

Watch the logs:

tail -f /var/log/ltm | grep "DNS TEST"

Expected: You should see IP addresses like 13.248.169.98 76.223.95.45

If empty or error: DNS resolution is failing in TMM even though tmsh list sys dns shows servers.

2. Capture network traffic

Use tcpdump to see if HTTPS requests are actually being sent:

# Capture outbound traffic to Centinel API
tcpdump -i 0.0 -n host validator.centinelanalytica.com -w /var/tmp/centinel-traffic.pcap

Generate some traffic to your application, then:

# Stop tcpdump (Ctrl+C), then analyze
tcpdump -r /var/tmp/centinel-traffic.pcap -n

Look for:

• DNS queries (port 53) - Should see A record requests
• SYN packets to port 443 - Should see connection attempts
• TLS handshakes - Should see successful SSL negotiation

If you see no traffic: The SIDEBAND connection isn't being attempted at all.

3. Check for firewall/routing issues

# Test routing to API
tmsh run util traceroute validator.centinelanalytica.com

# Check if firewall is blocking
tmsh run util curl -v --connect-timeout 5 https://validator.centinelanalytica.com/validate

If curl hangs or times out: Network path is blocked (firewall, routing, NAT issues).

4. Verify virtual server is actually listening

# Check if API virtual server is accepting connections
tmsh show ltm virtual centinel_api_ssl_vs

# Look for these fields:
# - Availability: available (should be green)
# - State: enabled
# - Reason: The virtual server is available

If unavailable: Virtual server configuration is wrong.

5. Enable maximum debug logging

Edit the Centinel iRule and enable all debug flags:

set static::CENTINEL_LOG_REQUEST_HEADERS 1
set static::CENTINEL_LOG_RESPONSE_HEADERS 1
set static::CENTINEL_LOG_REQUEST_TIME 1

Also, add detailed logging around the SIDEBAND call (around line 800-850 in the iRule):

# Find the SIDEBAND::connect line and add logging before/after
log local0. "CENTINEL DEBUG: Attempting SIDEBAND connection to $raddr"
set conn [SIDEBAND::connect ...]
log local0. "CENTINEL DEBUG: SIDEBAND result: [SIDEBAND::state $conn]"

Watch logs for detailed connection flow:

tail -f /var/log/ltm | grep -E "CENTINEL|SIDEBAND"

6. Test with hardcoded IP (temporary workaround)

As a diagnostic test, temporarily bypass DNS by hardcoding the IP:

# In Centinel iRule, around line 780-790, replace:
set raddr [RESOLV::lookup @validator.centinelanalytica.com]

# With:
set raddr "13.248.169.98"

If this works: Confirms DNS is the issue. Investigate why TMM DNS isn't resolving.

If this still fails: The problem isn't DNS—it's network connectivity, virtual server config, or SSL profile.

7. Check for TMM resource exhaustion

# Check TMM memory and connection limits
tmsh show sys tmm-info
tmsh show sys connection

# Check for error messages
grep -i "memory\|exhausted\|limit" /var/log/ltm

If TMM is resource-constrained: You may need to increase connection limits or add more resources.

8. Verify TLS compatibility

Test TLS handshake explicitly:

# Test TLS connection from F5
openssl s_client -connect validator.centinelanalytica.com:443 -showcerts

# Check for successful handshake and certificate chain

Look for: Verify return code: 0 (ok) or certificate verification errors.

Information to gather for support

If nothing above resolves your issue, collect this information before contacting Centinel support:

# 1. System information
tmsh show sys version
tmsh show sys provision

# 2. DNS configuration
tmsh list sys dns

# 3. Virtual server configs
tmsh list ltm virtual centinel_api_ssl_vs all-properties
tmsh list ltm virtual your_application_vs all-properties

# 4. iRule status
tmsh show ltm rule Centinel
tmsh show ltm rule Centinel-SSL-Helper

# 5. Recent logs (last 200 lines with CENTINEL)
grep CENTINEL /var/log/ltm | tail -200

# 6. Network test results
run /util dig validator.centinelanalytica.com
run /util curl -v https://validator.centinelanalytica.com/validate

# 7. Active connections
tmsh show ltm virtual centinel_api_ssl_vs

Package this information and include:

• Description of the problem (exact error messages)
• When it started (after config change? Always?)
• Traffic patterns (all requests failing? Intermittent?)
• Any recent changes to F5 configuration

Fail-open architecture

The integration uses fail-open behavior for maximum reliability:

• API timeout → Request allowed
• API unreachable → Request allowed
• Network error → Request allowed
• DNS failure → Request allowed
• SSL error → Request allowed

Only when the API explicitly returns block is traffic blocked.