How to make.htaccess rewrites work in OpenLiteSpeed

OpenLiteSpeed understands Apache-style rewrite rules, but it does not treat .htaccess the way Apache does. Rewrites must be switched on per virtual host, only rewrite directives are read, and changes are not always picked up until the server restarts. Most "my permalinks return 404" problems on OpenLiteSpeed come from one of these three points. This guide fixes each one.

Before you start

• An OpenLiteSpeed server with a virtual host for your site. See Add virtual hosts and domains in OpenLiteSpeed.
• WebAdmin access and SSH access with sudo.
• The path to the site's document root, for example /var/www/example.com/html.

How OpenLiteSpeed handles.htaccess

Apache reads every .htaccess file on every request. That is flexible but costs time. OpenLiteSpeed does something cheaper:

• It only reads rewrite rules from .htaccess when Auto Load from.htaccess is on for the virtual host.
• It reads and caches the rules, rather than checking the file on every request.
• It supports the mod_rewrite directives: RewriteEngine, RewriteBase, RewriteCond and RewriteRule. Other Apache directives in the file are ignored.

So a rule that works on Apache may do nothing on OpenLiteSpeed, either because rewrites are off or because the server has not reloaded the file.

Step 1: Turn on rewrites for the virtual host

1. Log in to WebAdmin at https://203.0.113.10:7080.
2. Go to Virtual Hosts, open your site and choose the Rewrite tab.
3. Edit Rewrite Control and set:

• Enable Rewrite: Yes
• Auto Load from.htaccess: Yes

1. Save, then click Graceful Restart at the top right.

If your virtual host was created from a template, check the template's Rewrite settings too, because the vhost may inherit them.

Step 2: Restart after every.htaccess change

Because OpenLiteSpeed caches the rules, an edited .htaccess file may not take effect straight away. After you change it, by hand or through a plugin, restart the server gracefully:

sudo /usr/local/lsws/bin/lswsctrl restart

A graceful restart finishes requests in progress, so visitors do not see errors. This includes changes made by WordPress itself, such as saving the Permalinks page or activating a security or cache plugin that writes rules.

Step 3: Know which directives work

These work in .htaccess on OpenLiteSpeed:

RewriteEngine On
RewriteBase /
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule . /index.php [L]

These are ignored in .htaccess and must be configured another way:

• php_value and php_flag: set them in the LSPHP php.ini, or in the vhost's PHP ini Override setting under General.
• Options, DirectoryIndex, ErrorDocument: set Index Files and Customized Error Pages in the vhost.
• AuthType, Require, Order, Deny: use a Context with a Realm in the vhost for passwords, and the vhost's Security → Access Control for IP rules.
• Header and Expires blocks: add them in a vhost Context with Header Operations.

LiteSpeed Cache rules wrapped in <IfModule LiteSpeed> are understood, because the plugin writes them for this server.

Step 4: Fix 404 on WordPress permalinks

Work through this list in order:

1. Check the .htaccess file exists in the WordPress root and contains the standard block:

   sudo cat /var/www/example.com/html/.htaccess

You should see the lines between # BEGIN WordPress and # END WordPress. If the file is missing, go to Settings → Permalinks in WordPress and click Save Changes.

1. Check WordPress can write the file. If it cannot, it shows the rules for you to copy at the bottom of the Permalinks page. Create the file by hand and paste them in.
2. Confirm both rewrite options are on, as in Step 1.
3. Restart OpenLiteSpeed so it loads the rules.
4. Check the document root in the vhost points at the folder that contains .htaccess. A .htaccess file one level above the document root is never read.

If WordPress lives in a sub-folder such as /blog, its .htaccess must be in that folder, with RewriteBase /blog/ and RewriteRule. /blog/index.php [L].

Put rules in the virtual host instead

For rules that rarely change, such as a forced HTTPS redirect, you can paste them into the Rewrite Rules box on the vhost's Rewrite tab. They load with the server config and are not affected by plugins that rewrite .htaccess. Keep app rules, such as WordPress permalinks, in .htaccess so the app can manage them.

Check it works

1. Request a pretty URL with curl:

   curl -I https://example.com/hello-world/

You should get 200, not 404.

1. Request a page that does not exist, such as /no-such-page/. WordPress should return its own 404 page, which proves requests reach index.php.
2. Check the vhost error log in WebAdmin under Logs or in /usr/local/lsws/logs/error.log for rewrite errors.

Troubleshooting

• Rules work for a while, then stop after a plugin update: the plugin rewrote .htaccess. Restart OpenLiteSpeed and check the file is still valid.
• Only the home page works: rewrites are off or the server has not reloaded. Recheck Step 1 and restart.
• 500 error after adding a rule: a syntax error in the rule. Check the error log, fix the line and restart.
• Rule copied from Apache does nothing: it uses an unsupported directive. Move it into the vhost settings as shown in Step 3.

Next steps

• Set up WordPress on this server: Install WordPress on OpenLiteSpeed with LSCache.
• Compare how each web server handles rewrites: Nginx vs Apache vs OpenLiteSpeed for WordPress.
• Write redirect rules: Apache redirects with.htaccess.