Config File Syntax

OpenLiteSpeed uses a structured plain-text config format. You can edit these files directly with vim and apply changes with a graceful reload — no WebAdmin required.

Config Locations

• Server config: /usr/local/lsws/conf/httpd_config.conf
• Per-site config: /usr/local/lsws/conf/vhosts/<name>/vhconf.conf

---

httpd_config.conf — Server Level Structure

/usr/local/lsws/conf/httpd_config.conf

# ============================================================
# SERVER-LEVEL SETTINGS
# ============================================================

serverName                your-hostname

# Worker process count (0 = auto-detect CPU count)
workerProcesses           0

# User/group the workers run as
runAs                     nobody:nogroup

# Logging
errorlog /usr/local/lsws/logs/error.log {
  useServer               0
  logLevel                WARN
  rollingSize             10M
}

accesslog /usr/local/lsws/logs/access.log {
  useServer               0
  logFormat               "%h %l %u %t \"%r\" %>s %b"
  logHeaders              5
  rollingSize             100M
  compressArchive         0
}

# ============================================================
# LISTENER — HTTP on port 80
# ============================================================
listener HTTP {
  address                 *:80
  secure                  0
  map                     example *
}

# ============================================================
# LISTENER — HTTPS on port 443
# ============================================================
listener HTTPS {
  address                 *:443
  secure                  1
  keyFile                 /etc/ssl/private/example.key
  certFile                /etc/ssl/certs/example.crt
  certChain               1
  map                     example *

  # TLS settings
  sslProtocol             24          # TLS 1.2 + 1.3 only
  enableECDHE             1
  renegProtection         1

  # Enable HTTP/2
  alpn                    h2,http/1.1
}

# ============================================================
# VIRTUAL HOST REFERENCE
# ============================================================
virtualhost example {
  vhRoot                  /usr/local/lsws/conf/vhosts/example/
  configFile              $VH_ROOT/vhconf.conf
  allowSymbolLink         1
  enableScript            1
  restrained              0
}

# ============================================================
# EXTERNAL APPLICATION (lsphp)
# ============================================================
extprocessor lsphp84 {
  type                    lsapi
  address                 uds://tmp/lshttpd/lsphp84.sock
  maxConns                35
  env                     PHP_LSAPI_CHILDREN=35
  env                     LSAPI_AVOID_FORK=200M
  initTimeout             60
  retryTimeout            0
  persistConn             1
  respBuffer              0
  autoStart               2
  path                    /usr/local/lsws/lsphp84/bin/lsphp
  backlog                 100
  instances               1
  priority                0
  memSoftLimit            2047M
  memHardLimit            2047M
  procSoftLimit           400
  procHardLimit           500
}

---

vhconf.conf — Virtual Host Structure

/usr/local/lsws/conf/vhosts/example/vhconf.conf

# ============================================================
# VIRTUAL HOST — BASIC SETTINGS
# ============================================================

docRoot                   /var/www/example.com/public
vhDomain                  example.com, www.example.com
vhAliases                 www.example.com
adminEmails               admin@example.com
enableGzip                1
enableBr                  1

# ============================================================
# INDEX FILES
# ============================================================
index  {
  useServer               0
  indexFiles              index.php, index.html, index.htm
  autoIndex               0
  autoIndexURI            /_autoindex/default.php
}

# ============================================================
# LOGGING (per-vhost)
# ============================================================
errorlog  {
  useServer               1    # 1 = use server-level log
}

accesslog /usr/local/lsws/logs/example-access.log {
  useServer               0
  logFormat               "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\""
  logHeaders              5
  rollingSize             100M
}

# ============================================================
# PHP SCRIPT HANDLER
# ============================================================
scripthandler  {
  add                     lsapi:lsphp84 php
}

# ============================================================
# ACCESS CONTROL
# ============================================================
accessControl  {
  allow                   *
}

# ============================================================
# REWRITE RULES
# ============================================================
rewrite  {
  enable                  1
  autoLoadHtaccess        1

  rules                   <<<END_RULES
# Force HTTPS
RewriteEngine On
RewriteCond %{HTTPS} off
RewriteRule ^(.*)$ https://%{HTTP_HOST}%{REQUEST_URI} [R=301,L]
END_RULES
}

# ============================================================
# RESPONSE HEADERS (security)
# ============================================================
vhssl  {
  keyFile                 /etc/ssl/private/example.key
  certFile                /etc/ssl/certs/example.crt
  certChain               1
  clientVerify            0
}

# ============================================================
# CONTEXT — Custom path rules
# ============================================================

# Block access to hidden files
context /.well-known {
  location                /var/www/example.com/public/.well-known
  allowBrowse             1
  accessControl  {
    allow                 *
  }
}

context /wp-admin {
  allowBrowse             1
  accessControl  {
    allow                 192.168.1.0/24, *
  }
}

---

Common Directives — Quick Lookup

Server Level (httpd_config.conf)

Directive	Example Value	What It Does
workerProcesses	0	Worker count (0 = auto)
runAs	nobody:nogroup	Process user/group
listener	{ address *:80; }	Port binding
extprocessor	{ type lsapi; ... }	External PHP app
virtualhost	{ configFile ...; }	Per-site reference
sslProtocol	24	8=TLS1.1, 16=TLS1.2, 24=1.2+1.3
enableECDHE	1	Elliptic-curve key exchange

Virtual Host Level (vhconf.conf)

Directive	Example Value	What It Does
docRoot	/var/www/site/public	Web root path
vhDomain	site.com, www.site.com	Domain names
enableGzip	1	Enable gzip compression
enableBr	1	Enable Brotli compression
scripthandler	lsapi:lsphp84 php	Map .php to lsphp
phpIniOverride	memory_limit=512M	Per-vhost php.ini overrides
rewrite enable	1	Enable rewrite engine
autoLoadHtaccess	1	Load .htaccess files

---

.htaccess — Rewrite Rules

OLS supports .htaccess with autoLoadHtaccess 1 in the vhost.

WordPress .htaccess

# Standard WordPress
<IfModule mod_rewrite.c>
RewriteEngine On
RewriteBase /
RewriteRule ^index\.php$ - [L]
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule . /index.php [L]
</IfModule>

Force HTTPS

RewriteEngine On
RewriteCond %{HTTPS} off
RewriteRule ^(.*)$ https://%{HTTP_HOST}%{REQUEST_URI} [R=301,L]

Block XML-RPC

<Files xmlrpc.php>
  Order Deny,Allow
  Deny from all
</Files>

---

Apply Changes Workflow

# 1. Edit a config file
sudo vim /usr/local/lsws/conf/vhosts/example/vhconf.conf

# 2. Graceful reload (no downtime)
sudo /usr/local/lsws/bin/lswsctrl restart

# 3. Check for errors immediately
sudo tail -20 /usr/local/lsws/logs/error.log

# 4. Test with curl
curl -H "Host: example.com" -I http://localhost/