Migrating from Nginx, Apache, Caddy or OpenLiteSpeed
miraserve import reads a config file from another web server and writes a draft MiraServe config. This page shows how to use it and what it does when it cannot translate a security rule. It also covers what you must still check by hand before you switch traffic.
Treat the output of miraserve import as a draft, never as a finished config. The importer can still miss access rules, PHP handling and security headers in some configs, and in some of those cases it reports success. Read the migration notes, run miraserve check --strict, and compare access rules, authentication, PHP handling and security headers with the old server by hand. Test the result before you switch traffic.
Supported sources
--from | Reads |
|---|---|
auto | Detects the format (default). |
nginx | nginx.conf or a file from sites-enabled/ |
apache | <VirtualHost> configs, apache2.conf, httpd.conf |
caddy | Caddyfile |
openlitespeed | vhconf.conf or httpd_config.conf |
The importer reads one file, or standard input when you pass -. It does not follow include lines. A few stock include paths, such as /etc/nginx/mime.types, snippets/fastcgi-php.conf and the Certbot options-ssl-*.conf files, are assumed safe and listed in the notes. Any other include stops the import, because the importer cannot see what is in it.
A first import
Take a small Nginx site:
server {
listen 443 ssl http2;
server_name example.com;
root /var/www/example;
location / {
try_files $uri $uri/ =404;
}
}
$ miraserve import /etc/nginx/sites-enabled/example.conf --output example.kdl
Migrated 1 site(s) and 1 route(s) from nginx configuration.
Wrote validated MiraServe KDL to 'example.kdl'.
Security upgrades applied:
+ Enforced TLS 1.3 default with X25519MLKEM768 post-quantum hybrid key exchange
+ Enabled HTTP/3 + HTTP/2 + HTTP/1.1 listener defaults and strict security headers
+ Enabled Linux Landlock LSM and seccomp-bpf worker sandboxing defaults
The generated file:
server {
listen ":443" protocols="h3,h2,h1"
listen ":80" redirect-https=#true
tls {
min-version "1.3"
pqc-hybrid #true
key-isolation "in-process"
}
sandbox {
landlock #true
seccomp "strict"
}
}
site "example.com" {
security-headers "strict"
root "/var/www/example"
route "/*" {
try-files "{path}" "{path}/" "=404"
}
}
Without --output, the config goes to standard output and the notes to standard error. --output never replaces an existing file unless you add --force. For a machine-readable report, use --format json. It contains the generated config plus the lists security_upgrades, security_downgrades, insecure_sites_emitted, notes and validation_warnings.
The generated file has no certificate yet. Add an ACME block or your own cert and key before you run it in production. See TLS and certificates.
Security downgrades
A security downgrade is a security control in the old config that the importer found but cannot translate into MiraServe exactly. Examples are password protection (auth_basic, Apache Require, Caddy basicauth), IP allow and deny lists, rate limits, ModSecurity or other WAF rules, client certificate checks, blocking return or RewriteRule rules, prefix-stripping proxy_pass, OpenLiteSpeed LSAPI, and includes the importer cannot read.
If the importer finds a downgrade, it stops. It exits with a non-zero status and does not write the output file, so you cannot deploy a config that has quietly lost a protection:
server {
listen 443 ssl http2;
server_name example.com;
root /var/www/example;
location /admin/ {
auth_basic "Restricted";
auth_basic_user_file /etc/nginx/.htpasswd;
}
}
$ miraserve import admin.conf --output admin.kdl
SECURITY ERROR: 2 security directive(s) in nginx config could not be auto-translated (affected routes were omitted):
! line 6 (auth_basic): Nginx location '/admin/' uses 'auth_basic' which cannot be auto-translated; route omitted to avoid exposing protected endpoint
! line 7 (auth_basic_user_file): Nginx location '/admin/' uses 'auth_basic_user_file' which cannot be auto-translated; route omitted to avoid exposing protected endpoint
Refusing to exit 0 or write output file. Re-implement the listed access controls manually, or re-run with --allow-insecure to export an INSECURE draft (including blocked sites tagged '// INSECURE:') for offline review only.
You then have to rebuild the missing control yourself and edit the draft by hand. The current version of MiraServe has no built-in password protection and no IP allow or deny lists in its config. For a protected area, your options are to require client certificates for the whole site (a per-site client-ca in the site's tls block), to enforce the check in the backend application, or to leave the path out of the public site. Rate limits translate to rate-limit.
What --allow-insecure does
--allow-insecure tells the importer to write the draft anyway and exit 0, even though a security control could not be translated. Use it only to read the draft offline. Never deploy its output as it is.
Be careful with what “omitted” means. In the example above, --allow-insecure drops the /admin/ route, but the site keeps root "/var/www/example". Anything under /var/www/example/admin/ would then be served as ordinary static files, with no password. The protected path is not blocked. It is just no longer protected. Re-create every control listed in the warning before this config gets near real traffic.
What the importer can miss
The downgrade check catches many controls, but not all of them. Some configs import with exit status 0 and no warning, yet behave differently from the old server. Check these areas by hand every time.
Access rules
Rules written in an unusual form, spread over several lines, placed in an http-level file, or expressed as a rewrite can be lost without a downgrade. List every protected path on the old server and request each one against the new config.
PHP handling
MiraServe runs PHP only through a fastcgi-pass route. If the old server ran PHP in a way the importer does not recognise, the draft can come out with a document root but no PHP route. For example, an Apache vhost that only sets DirectoryIndex index.php imports cleanly as a plain static site. A site without a PHP route treats .php files as ordinary files. A request for /config.php then returns the PHP source code, including any passwords in it, and check --strict does not warn about this. Make sure every PHP site in the draft has a route "*.php" with fastcgi-pass.
Also check the route order. A route matches in the order written, and in some imports the catch-all "/*" route comes before "*.php". check --strict reports this as warning W014. Put the PHP route first. A complete corrected config, with ACME added, looks like this:
server {
listen ":443" protocols="h3,h2,h1"
listen ":80" redirect-https=#true
tls {
acme {
email "[email protected]"
challenge "tls-alpn-01"
}
}
}
site "blog.example.com" {
preset "wordpress-hardened"
security-headers "strict"
root "/var/www/blog"
route "*.php" {
fastcgi-pass "unix:/run/php/php8.3-fpm.sock"
}
route "/*" {
try-files "{path}" "{path}/" "/index.php?{query}"
}
}
The importer may switch on preset "wordpress-hardened" when it sees a try_files … /index.php pattern, also for sites that are not WordPress. That preset blocks PHP only under wp-content/uploads and wp-includes. If the old server denied PHP in other upload folders, write those rules yourself. Settings passed to PHP from the web server, such as open_basedir in fastcgi_param PHP_ADMIN_VALUE or OpenLiteSpeed phpIniOverride, are not carried over. Move them into the PHP-FPM pool config.
Security headers
Headers set with Nginx add_header, Caddy header or Apache Header are not translated, and the importer may not mention them. MiraServe adds its own headers through security-headers "strict" (HSTS, X-Content-Type-Options, Referrer-Policy, X-Frame-Options, Cross-Origin-Opener-Policy, Permissions-Policy), but that set does not include a Content-Security-Policy. If your old server sent a CSP, you must add it again.
Other differences
- Apache
.htaccessfiles are not read at runtime. Move their rules into the KDL file. mod_phpand OpenLiteSpeed LSAPI are not supported. Use PHP-FPM over a Unix socket.- Nginx
proxy_pass http://host/;strips the location prefix, but MiraServe forwards the original path unchanged. The importer treats this as a downgrade. - TLS 1.2 is turned off. Add
compat-tls-1-2 #trueto a single site'stlsblock only if its clients still need it. - For Apache, listen addresses kept in a separate
ports.confare not read, so a loopback-only vhost can come out on a public port. Check everylistenline.
A safe migration workflow
- Import each site to a file and read every note and warning:
$ miraserve import /etc/nginx/sites-enabled/blog.conf --from nginx --output blog.kdl $ miraserve import /etc/nginx/sites-enabled/blog.conf --from nginx --format json - Add TLS (ACME or your own certificate) and validate strictly, including the files on disk:
Fix every error and warning. A draft the importer called “validated” can still fail$ miraserve check --strict --fs blog.kdl--strict. - Compare with the old server by hand: every protected path, every authentication rule, every IP restriction, PHP handling for every site, and every security header.
- Run MiraServe next to the old server on other ports, for example 8443 and 8080, and test with real requests. Include requests that should be refused, such as protected paths,
.phpfiles in upload folders and dotfiles. Check both IPv4 and IPv6 (curl -4andcurl -6) and HTTP/3 (curl --http3-only). - Only then stop the old server and start MiraServe on ports 80 and 443. See Deployment.
Related pages
- PHP and WordPress
- Reverse proxy
- CLI commands (full
importflags)