Skip to main content

Installation and Initialization

Overview​

BotManager Fastly Agent is an edge-based bot detection and blocking solution that operates on the Fastly Compute platform.

Key Features:

  • Real-time bot/macro detection and blocking
  • Session-based user management
  • Provides captcha/challenge pages
  • Configuration-based bypass logic

What is Fastly Compute?​

Fastly Compute is a serverless edge computing platform based on WebAssembly (WASM).

Features:

  • Runs at edge locations worldwide
  • Ultra-fast response time (sub-millisecond)
  • Auto-scaling
  • Developer-friendly environment

For more information about Fastly Compute, refer to Fastly Official Documentation.

info

This guide covers how to add BotManager Agent to an existing environment where Fastly Compute Service is already running.

Installation Methods​

Follow these 4 steps in order to install BotManager Fastly Agent.

1. Configure Origins​

Register BotManager detection server as an Origin.

  1. Navigate to Origins tab of the Compute Services to install

  2. Click Create a host

  3. Enter the following information:

    FieldValueDescription
    Namebotmanager_serverOrigin name
    Addressbotmanager.stclab.comDetection server address
    Port443HTTPS port
    Use SSL✅ CheckUse SSL
    Certificate hostnamebotmanager.stclab.comCertificate hostname
Origins Configuration Tips

After configuring Origin, verify that it connects properly through connection test.

2. Upload Package​

Upload BotManager Fastly Agent package.

  1. Download BotManager Fastly Agent:

    https://cdn-botmanager.stclab.com/agents/cdn/fastly/botmanager-fastly-agent.tar.gz

  2. Navigate to Package tab

  3. Click Upload new package

  4. Select the downloaded botmanager-fastly-agent.tar.gz file or upload via Drag and drop

  5. Confirm Upload success message

Package Version

After package upload, check version information to verify that the correct version was uploaded.

3. Configure Config Stores​

Store BotManager Agent configuration values in Config Store.

  1. Navigate to Resources → Config stores

  2. Click Create store

  3. Enter Store name: bm_config

  4. Click Add item and add the following configuration items

Required Configuration Check

Select the domain below to accurately verify the domain to apply.

Required Configuration​

The following configurations must be added:

KeyValueDescription
BM_TENANT_ID{TENANT ID}Customer identifier (check in BotManager console)
BM_DOMAIN_NAME{DOMAIN}Target domain to apply (e.g., example.com)
Missing Required Configuration

If required configuration is missing, Agent will not operate properly. Be sure to check.

Optional Configuration​

The following configurations operate with default values and should only be changed when necessary:

KeyDefault ValueDescription
BM_SERVER_URLhttps://botmanager.stclab.com/api/v1/macroDetection server URL
BM_PROTECTION_URLhttps://cdn-botmanager.stclab.comBlock page URL
BM_STATIC_BYPASStrueWhether to bypass static resources
BM_BYPASSfalseWhether to bypass all
BM_SERVER_TIMEOUT1000Detection server timeout (ms)
BM_LOGLEVELERRORLog level (WARN, INFO, DEBUG)
BM_EXCLUDED_PATHS/api,/healthExcluded paths (comma-separated)
BM_EXCLUDED_QUERYSuser,passwordExcluded queries (comma-separated)
Using Optional Configuration

To exclude specific paths or query parameters from detection, use BM_EXCLUDED_PATHS and BM_EXCLUDED_QUERYS.

4. Service Activation​

Activate the configured service and initialize cache.

  1. Click Add version comment and enter deployment details

    Example: "BotManager Agent v1.0.1 deployment"

  2. Click Activate in Service configuration tab

  3. Click Purge all in Service summary tab to initialize cache

Post-Activation Verification

After Service activation, verify that Agent headers are properly added in actual requests.

Basic Operation Testing​

After installation is complete, verify that Agent is operating properly.

Verify Agent Headers​

Check Agent headers through browser developer tools.

  1. Open Browser Developer Tools (F12)

  2. Select Network tab

  3. Access protected site

  4. Check the following header in Response Headers:

x-bm-agent: BM-fastly-agent-x.x.x
Header Verification Tips

If header is not visible in the first request, refresh the page or clear cache and try again.

Verify Session Cookies​

Check session cookies created by Agent.

  1. Select Application tab (Chrome) or Storage tab (Firefox)

  2. Check the following cookie in Cookies section:

BM-session-id: [Generated session ID]
  1. Test via command line:
# Check headers using curl
curl -I https://your-domain.com

# Expected result:
# HTTP/2 200
# x-bm-agent: BM-fastly-agent-1.0.1
# set-cookie: BM-session-id=...
Session Cookies

Session cookies are automatically created to track user sessions. They may not be created depending on browser cookie settings.

Troubleshooting​

Guidance on problems that may occur during installation and operation and their solutions.

Agent Headers Not Visible​

Symptom: x-bm-agent header not displayed in Response Headers

Possible Causes:

  • Service not activated
  • Package upload failure
  • Configuration error

Solutions:

  1. Check Service Status

    • Check activation status in Service configuration tab
    • If inactive, click Activate and retry

  2. Re-upload Package

    • Check latest version in Package tab
    • Re-upload package if necessary

  3. Re-verify Config Store Settings

    • Check required configuration items (BM_TENANT_ID, BM_DOMAIN_NAME)
    • Verify Store name is bm_config
Service Activation Required

If Service is not activated, Agent will not operate. Be sure to check activation status.

Detection Server Connection Failure​

Symptom: Following error message displayed in Response Headers

x-bm-error: Detection server timeout

Solutions:

  1. Check Origins Configuration

    • Verify Backend address is botmanager.stclab.com
    • Verify SSL configuration is correct
    • Verify Port is 443

  2. Adjust Timeout Settings

    • Increase BM_SERVER_TIMEOUT value in Config Store
    • Default: 1000ms → Increase to 2000ms or higher if necessary

  3. Check Network Connection Status

    • Verify connectivity from Fastly to botmanager.stclab.com
Timeout Settings

In environments with network latency, it is recommended to appropriately increase the BM_SERVER_TIMEOUT value.

Config Store Access Error​

Symptom: Following error message displayed in Response Headers

x-bm-error: Config initialization failed

Solutions:

  1. Check Config Store Name

    • Verify Store name is exactly bm_config
    • Note case sensitivity

  2. Check Required Configuration Items

    • Verify both BM_TENANT_ID and BM_DOMAIN_NAME are set
    • Verify values are entered correctly

  3. Check Service Connection

    • Verify Config Store is properly connected to Service
    • Check connection status in Resources tab
Config Store Error

If Config Store access error occurs, Agent will not operate at all. This must be resolved.