Configuration testing (nginx -t) - Commands & Configuration

Introduction

When you change your nginx settings, you want to make sure they are correct before restarting the server. Configuration testing checks your settings for mistakes without stopping your website.

After editing nginx configuration files to add a new website or change settings

Before restarting nginx to avoid downtime caused by configuration errors

When troubleshooting nginx to verify if the current configuration is valid

Before deploying configuration changes to a production server

When automating nginx setup in scripts or CI/CD pipelines to catch errors early

Config File - nginx.conf

nginx.conf

user nginx;
worker_processes auto;
error_log /var/log/nginx/error.log warn;
pid /var/run/nginx.pid;

events {
    worker_connections 1024;
}

http {
    include /etc/nginx/mime.types;
    default_type application/octet-stream;

    log_format main '$remote_addr - $remote_user [$time_local] "$request" '
                    '$status $body_bytes_sent "$http_referer" '
                    '"$http_user_agent" "$http_x_forwarded_for"';

    access_log /var/log/nginx/access.log main;

    sendfile on;
    keepalive_timeout 65;

    server {
        listen 80;
        server_name example.com www.example.com;

        location / {
            root /usr/share/nginx/html;
            index index.html index.htm;
        }
    }
}

This is a basic nginx configuration file.

• user nginx; sets the user running nginx.
• worker_processes auto; lets nginx decide how many worker processes to use.
• events block sets worker connections.
• http block configures web server settings, including logging and server blocks.
• server block listens on port 80 for example.com and serves files from /usr/share/nginx/html.

Commands

This command tests the nginx configuration files for syntax errors and validity without restarting the server. It helps catch mistakes before applying changes.

Terminal

sudo nginx -t

Expected Output

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok

nginx: configuration file /etc/nginx/nginx.conf test is successful

→

-t - Test configuration files for syntax errors

After confirming the configuration is valid, this command reloads nginx to apply the new settings without stopping the server.

Terminal

sudo systemctl reload nginx

Expected Output

No output (command runs silently)

An alternative way to reload nginx gracefully using the nginx command itself after successful configuration testing.

Terminal

sudo nginx -s reload

Expected Output

No output (command runs silently)

→

-s reload - Send reload signal to nginx to apply new configuration

Key Concept

If you remember nothing else from this pattern, remember: always run 'nginx -t' to check your configuration before restarting or reloading nginx.

Common Mistakes

Restarting nginx without testing configuration first

If there is a syntax error, nginx will fail to start, causing downtime.

Always run 'sudo nginx -t' to verify configuration before restarting or reloading.

Ignoring error messages from 'nginx -t'

Errors indicate problems that will prevent nginx from running correctly.

Read and fix all errors reported by 'nginx -t' before applying changes.

Running 'nginx -t' without sudo or proper permissions

The command may fail to read configuration files, giving false errors.

Run 'sudo nginx -t' or as a user with permission to read nginx config files.

Summary

Use 'sudo nginx -t' to check nginx configuration syntax and validity before applying changes.

If the test is successful, reload nginx with 'sudo systemctl reload nginx' or 'sudo nginx -s reload' to apply changes without downtime.

Never restart nginx without testing configuration first to avoid service interruptions.