Quick Start

Get Klixsor running on your server in under 5 minutes.

curl -sSL https://klixsor.com/install.sh | bash -s -- YOUR-LICENSE-KEY

Server Requirements

Ports Used

Installation

What the installer does

1. Installs system dependencies (curl, Docker, fail2ban, UFW)
2. Sets up Docker containers for PostgreSQL 16, ClickHouse, and Redis 7
3. Downloads Klixsor API and Click Engine binaries
4. Runs database migrations
5. Creates an admin user with a random password
6. Configures systemd services for auto-start on boot
7. Sets up UFW firewall (ports 22, 80, 443 only)
8. Seeds 17 bot IP lists and triggers initial sync

Installation command

curl -sSL https://klixsor.com/install.sh | bash -s -- YOUR-LICENSE-KEY

Custom version

To install a specific version instead of the latest:

curl -sSL https://klixsor.com/install.sh | bash -s -- --version 1.2.0 YOUR-LICENSE-KEY

File locations

First Steps After Install

1. Log in — Open http://YOUR-SERVER-IP/api/v1/auth/login with the credentials from the installer output
2. Add a tracking domain — Go to Domains → Add Domain. Point your domain's DNS A record to your server IP first.
3. Set up SSL — Click the shield icon (Setup SSL) on your domain row. This auto-provisions a Let's Encrypt certificate — no manual certbot commands needed.
4. Create a traffic source — Define where your traffic comes from (e.g., Facebook, Google Ads, push network)
5. Add offers — Add the affiliate offers you want to route traffic to
6. Create a campaign — Set up your first campaign with flows, landing pages, and offers
7. Verify bot detection — Check Bot Management → IP Lists to confirm all lists are synced
8. Check Settings — Go to Settings in the sidebar to verify your license status, version, and usage limits

Adding Domains

Adding a tracking domain to Klixsor is a 3-step process: configure DNS, add the domain in the admin panel, then provision SSL.

Step 1: Configure DNS

In your domain registrar (Namecheap, Cloudflare, GoDaddy, etc.), create a DNS record pointing to your Klixsor server.

For subdomains (recommended — e.g., track.yourdomain.com):

Type: A (or CNAME)
Name: track
Value: YOUR-SERVER-IP
TTL: 300 (or Auto)

For root domains (e.g., yourdomain.com):

Type: A
Name: @
Value: YOUR-SERVER-IP
TTL: 300 (or Auto)

Your server's IP is shown in the admin panel — the Domains page displays DNS setup instructions with the correct IP pre-filled.

Step 2: Add the domain in Klixsor

1. Go to Domains → Add Domain
2. Enter the full domain name (e.g., track.yourdomain.com)
3. Optionally set an Index Campaign to handle visitors to the domain root
4. Save the domain

Step 3: Setup SSL

Click the shield icon (Setup SSL) on the domain row. Klixsor will automatically:

• Verify DNS is pointing to your server
• Create an Nginx server block for the domain
• Provision a free Let's Encrypt SSL certificate
• Configure HTTPS with automatic HTTP → HTTPS redirect

The entire process takes about 10 seconds. Once complete, the SSL column will show Enabled.

SSL / HTTPS Setup

SSL is critical for tracking domains. Without HTTPS, browsers will show security warnings and may block redirects and tracking pixels.

Automatic SSL (recommended)

Klixsor handles SSL automatically. When you click the Setup SSL button on a domain, it:

1. Creates an Nginx server block for the domain
2. Obtains a free Let's Encrypt certificate via certbot
3. Configures HTTPS with automatic HTTP → HTTPS redirect
4. Sets up automatic certificate renewal (via systemd timer)

No manual configuration required. The installer pre-installs Nginx and Certbot for you.

Manual SSL (advanced)

If you prefer manual control, you can provision certificates yourself:

# Get a certificate manually
certbot certonly --nginx -d track.yourdomain.com

# Or use standalone mode (stops nginx temporarily)
certbot certonly --standalone -d track.yourdomain.com

# Certificates renew automatically via systemd timer
systemctl list-timers | grep certbot

Cloudflare (if using Cloudflare DNS)

Set Cloudflare SSL mode to Full (Strict) and use Cloudflare's origin certificate.

Nginx Reverse Proxy

Nginx is installed and configured automatically by the Klixsor installer. It proxies HTTPS traffic to the Klixsor services running on localhost.

How it works

The installer creates a base Nginx config at /etc/nginx/sites-available/klixsor-admin that:

• Proxies /api/ requests to the Admin API (:8081)
• Proxies all other requests to the Click Engine (:8090)

When you click Setup SSL on a domain, Klixsor creates a dedicated Nginx config at /etc/nginx/sites-available/klixsor-trk-{domain} with SSL termination.

Config files

# Base config (created by installer)
/etc/nginx/sites-available/klixsor-admin

# Per-domain configs (created by Setup SSL)
/etc/nginx/sites-available/klixsor-trk-track.yourdomain.com

# Check all configs
nginx -t

# Reload after manual changes
systemctl reload nginx

Custom Nginx config (advanced)

If you need to customize the Nginx config for a domain (e.g., add custom headers, rate limiting), edit the per-domain config file directly:

# Edit the tracking domain config
nano /etc/nginx/sites-available/klixsor-trk-track.yourdomain.com

# Test and reload
nginx -t && systemctl reload nginx

Configuration File

The main configuration is at /opt/klixsor/configs/config.yaml. Here are the key sections:

server:
  api_port: 8081          # Admin API port
  click_port: 8090        # Click engine port
  server_ip: ""           # Auto-detected if empty

postgres:
  host: localhost
  port: 5432
  user: klixsor
  password: "your-password"
  database: klixsor
  max_conns: 20           # Connection pool size

clickhouse:
  host: localhost
  port: 9000
  database: klixsor

redis:
  addr: localhost:6379
  password: "your-password"
  db: 0

bot_detect:
  score_threshold: 70     # Score >= 70 = definite bot (blocked)
  challenge_threshold: 40 # Score 40-69 = suspicious (challenge page)

geoip:
  db_path: "/var/lib/klixsor/GeoLite2-City.mmdb"

systemctl restart klixsor-api klixsor-clickengine

Creating Campaigns

Campaigns are the core of Klixsor. Each campaign has a unique URL that receives traffic and routes it based on your configured flows.

Campaign URL structure

https://track.yourdomain.com/CAMPAIGN-ALIAS?sub_id_1=value&sub_id_2=value

Campaign settings

Flows & Routing

Each campaign contains one or more flows. Flows determine which landing page and offer a visitor sees based on conditions you define.

Flow types

• Forced flow — Always used when its conditions match (top priority)
• Regular flow — Selected by weight among eligible flows
• Default flow — Fallback when no other flow matches

Flow conditions

Route traffic based on: country, device, OS, browser, language, connection type, ISP, referrer, sub ID values, day of week, hour of day, and more.

Landing Pages

Klixsor supports two types of landing pages:

Redirect landing pages

Klixsor redirects the visitor to your externally hosted landing page URL. The click URL is appended as a parameter so your page can link to the offer.

Local (hosted) landing pages

HTML stored and served directly by Klixsor. Use the Clone from URL feature to import any page:

1. Click "Clone from URL" in the Landing Pages section
2. Paste the URL of the page you want to clone
3. Klixsor fetches the HTML, rewrites all relative URLs to absolute, and saves it
4. Edit the HTML to add {offer_url} placeholders in your CTA buttons

Available placeholders

Offers

Offers are the destination URLs where traffic is ultimately sent. Add your affiliate offer URLs with the appropriate tracking parameters.

Offer URL with macros

https://network.com/offer?click_id={click_id}&sub1={sub_id_1}&sub2={sub_id_2}

Klixsor replaces all {placeholder} tokens with actual values when redirecting the visitor.

Conversion Tracking

Track conversions by adding a postback URL to your affiliate network. When a conversion happens, the network sends a request to Klixsor with the click ID.

Postback URL format

https://track.yourdomain.com/postback?click_id={click_id}&payout={payout}&status=approved

Replace {click_id} and {payout} with your network's corresponding macros.

Conversion parameters

Bot Detection — How It Works

Klixsor uses a multi-signal scoring system to detect bots. Every click is scored from 0 (human) to 255 (definite bot).

Detection signals

• IP reputation — Checked against 17 auto-synced datacenter/cloud IP lists (AWS, GCP, Azure, etc.)
• User agent analysis — Known bot UAs, suspicious patterns, empty/missing UA
• Header anomalies — Missing standard headers, unusual Accept-Language, etc.
• TLS fingerprint — Analyzes the TLS handshake for headless browser signatures
• DNS verification — Reverse DNS lookup for claimed crawlers (Googlebot, Bingbot)

Score thresholds

Bot Rules

Create custom rules to override bot scoring based on specific conditions. Rules are evaluated in priority order.

Conditions

Match on: IP address/range, user agent (contains/regex), country, ASN, referrer, header presence.

Actions

• Allow — Force-allow regardless of bot score
• Block — Return 403
• Safe page — Show the campaign's safe page
• Redirect — Send to a custom URL
• Challenge — Show a JavaScript challenge page

IP Lists

Klixsor auto-syncs 17 datacenter and cloud IP lists daily:

• Googlebot, Google Ads, Google Special Crawlers
• Bingbot, Applebot
• Facebook/Meta
• AWS, GCP, Azure, DigitalOcean, Oracle, Hetzner, OVH, Vultr, Linode, Scaleway, Cloudflare

Lists sync automatically on first install and every 24 hours thereafter. You can also add custom IP lists manually.

Updating Klixsor

Updates are safe and non-destructive. All your data, configuration, and credentials are preserved.

Check for updates

Go to Settings in the admin panel sidebar. The Version card shows:

• Current Version — the version running on your server
• Latest Version — the newest release available
• Update Available indicator — shown when a newer version exists

If an update is available, the Settings page displays the update command you need to run.

Update to the latest version

SSH into your server and run:

curl -sSL https://klixsor.com/install.sh | bash -s -- --update

What happens during an update

1. Backup — PostgreSQL database dump + config files saved to /var/lib/klixsor/backups/
2. Stop — Click engine and API gracefully stopped
3. Download — New binaries downloaded and validated (ELF header check prevents corrupt downloads)
4. Migrate — New database migrations applied (idempotent, safe to re-run)
5. Start — Services restarted
6. Verify — Health check confirms everything is running
7. Rollback — If the health check fails, old binaries and database are automatically restored

What's preserved

• All campaign, domain, and user data
• Click history and conversion data
• Configuration file (config.yaml)
• Database passwords and JWT secret (.env)
• License key
• Nginx configs and SSL certificates
• Firewall rules
• Admin credentials

Update to a specific version

curl -sSL https://klixsor.com/install.sh | bash -s -- --update --version 1.2.0

Skip backup (faster, not recommended)

curl -sSL https://klixsor.com/install.sh | bash -s -- --update --no-backup

Settings Page

The Settings page (accessible from the sidebar) provides a system overview with four information cards:

License

• Status — Active, Invalid, or Grace Period
• Plan — Your current subscription tier (Starter, Pro, Enterprise)
• License Key — Masked display of your license key
• Expires — License expiration date with a warning if expiring soon

Usage & Limits

Visual progress bars showing your current usage against plan limits:

• Campaigns — current / maximum campaigns
• Domains — current / maximum domains
• Users — current / maximum users

Bars turn yellow at 70% and red at 90% usage. "Unlimited" is shown for Enterprise plans.

Version

• Current Version — the version running on this server
• Latest Version — the newest version available from klixsor.com
• Update Available — indicator with the update command when a new version exists

Plan Features

Shows which features are included in your plan (e.g., landing page cloner, API access, custom bot rules). Only displayed when features are restricted by your plan.

Backups & Restore

Automatic backups

Every update creates an automatic backup at /var/lib/klixsor/backups/klixsor_backup_YYYYMMDD_HHMMSS/. The 5 most recent backups are kept.

Manual backup

# PostgreSQL dump
docker exec klixsor-postgres pg_dump -U klixsor -d klixsor \
  --format=custom -f /tmp/klixsor_backup.dump
docker cp klixsor-postgres:/tmp/klixsor_backup.dump ./klixsor_backup.dump

# Config files
cp /opt/klixsor/configs/config.yaml ./config.yaml.bak
cp /opt/klixsor/.env ./.env.bak

Restore from backup

# Stop services
systemctl stop klixsor-api klixsor-clickengine

# Restore PostgreSQL
docker cp klixsor_backup.dump klixsor-postgres:/tmp/restore.dump
docker exec klixsor-postgres pg_restore -U klixsor -d klixsor \
  --clean --if-exists /tmp/restore.dump

# Restore config
cp config.yaml.bak /opt/klixsor/configs/config.yaml

# Restart
systemctl start klixsor-api klixsor-clickengine

License Management

How licensing works

• Your license key is stored at /opt/klixsor/license.key
• Klixsor validates the license with the Klixsor license server every 6 hours
• If the server is unreachable, a 72-hour grace period allows continued operation
• Plan limits (campaigns, domains, users) are enforced based on your subscription tier

Update your license key

# Method 1: Via the update script
curl -sSL https://klixsor.com/install.sh | bash -s -- --update NEW-LICENSE-KEY

# Method 2: Manually
echo "NEW-LICENSE-KEY" > /opt/klixsor/license.key
systemctl restart klixsor-api klixsor-clickengine

Plan limits

Troubleshooting

# Check service status and logs
systemctl status klixsor-api
journalctl -u klixsor-api -n 50 --no-pager

systemctl status klixsor-clickengine
journalctl -u klixsor-clickengine -n 50 --no-pager

# Check if Docker containers are running
docker ps

# Find what's using port 8081
fuser 8081/tcp
# Kill the process
fuser -k 8081/tcp
# Restart
systemctl restart klixsor-api

# Check if PostgreSQL is running
docker exec klixsor-postgres pg_isready -U klixsor

# Restart Docker containers
cd /opt/klixsor && docker compose --env-file .env up -d

# Verify password matches config
grep password /opt/klixsor/configs/config.yaml
grep POSTGRES_PASSWORD /opt/klixsor/.env

# Check license key
cat /opt/klixsor/license.key

# Test connectivity to license server
curl -s https://klixsor.com/api/license/validate

# Check logs for license errors
journalctl -u klixsor-api | grep license

# Restart the API to trigger sync
systemctl restart klixsor-api

# Check logs for sync status
journalctl -u klixsor-api | grep "bot.*sync"

API Authentication

The Klixsor API uses JWT tokens. Obtain a token by logging in, then include it in the Authorization header.

Login

curl -X POST https://admin.yourdomain.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"login": "admin", "password": "your-password"}'

# Response:
# { "token": "eyJhbGciOi...", "refresh_token": "..." }

Authenticated request

curl https://admin.yourdomain.com/api/v1/campaigns \
  -H "Authorization: Bearer YOUR-JWT-TOKEN"

API Endpoints

All endpoints are under /api/v1/ and require JWT authentication (except login).

All list endpoints support ?page=1&per_page=50&sort_by=id&sort_dir=desc&search=term query parameters.

Postback URL

Configure this postback URL in your affiliate network to track conversions:

https://track.yourdomain.com/postback?click_id=REPLACE&payout=REPLACE&status=approved

Replace REPLACE with your network's macros for click ID and payout.