Nginx Configuration Guide

Nginx is a lightweight, high-performance web server and reverse proxy server, characterized by low memory usage and strong concurrency. Nginx adopts an event-driven + asynchronous non-blocking I/O model. Compared with the traditional multi-process/multi-thread model, it can maintain low resource consumption and high response speed in high-concurrency scenarios. The architecture of Nginx consists of a master process and multiple worker processes. The master process is responsible for reading and evaluating the configuration and managing the worker processes; the worker processes handle the actual client requests.

Nginx Instructions for Use

Server configuration file and path description

1.For the server configuration block files that need to be loaded for the Nginx service, this block is used to define a virtual host (Virtual Host), which can distinguish different websites based on domain names, IP addresses, and ports. An http block can contain multiple server blocks. Here is an example:

   server {
    listen 17.1.1.2:188 ssl;
    ignore_invalid_headers off;
    #access_log /var/log/ngx_access.log;
    #error_log /var/log/ngx_error.log;
    access_log off;
    resolver 8.8.8.8 valid=5 ipv6=off;

    ssl_certificate /etc/sonic/nginx/cert/asterfusion.crt;
    ssl_certificate_key /etc/sonic/nginx/cert/asterfusion.key;
    location ^~ / {
        #proxy_pass http://108.0.0.10:80;
        #proxy_set_header Host $host;
        #proxy_set_header X-Real-IP $remote_addr;
        #proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        #proxy_set_header X-Forwarded-Proto $scheme;

        root /etc/sonic/nginx_mmc;
        index 16K.txt;
        try_files $uri $uri/ =404;
    }
}

If SSL encrypted request access is used in similar files as above, the certificate file path needs to be specified simultaneously; otherwise, it does not need to be specified.

2.For situations where there is a need to differentiate user access to different resources based on URLs, we can use a configuration file similar to the following for loading:

  server {
    listen 17.1.1.2:188 ssl;
    ignore_invalid_headers off;

    #access_log /var/log/ngx_access.log;
    #error_log /var/log/ngx_error.log error;
    resolver 8.8.8.8 valid=5 ipv6=off;

    ssl_certificate /etc/sonic/nginx/cert/asterfusion.crt;
    ssl_certificate_key /etc/sonic/nginx/cert/asterfusion.key;

    location /static/ {
        alias /etc/sonic/nginx_mmc/;
        index index.html;
    }

    location ^~ / {
        proxy_pass http://108.0.0.10:80;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

In the server configuration file mentioned above, when the client specifies a URL ending with the /static/ path, it accesses resources in the mmc partition; otherwise, all requests are proxied. Users can customize server files to load Nginx services according to their needs. Note that nginx reload must be executed after every file update. All Nginx configuration files are stored under /etc/sonic/nginx/. If users require Nginx configurations to persist after a device reload or reboot, they must execute the write command to save the configuration. Regarding the directory structure under /etc/sonic/nginx/: The conf folder stores the currently running Nginx configurations. The saved folder stores the Nginx configurations that have been saved on the device (via the write command). The configed folder stores the configurations that are read whenever nginx reload is executed. Important: Users should note that if you intend to load configurations by directly modifying files in this path, you must modify the files under configed. Do not modify the files under conf; otherwise, the modifications will be overwritten and become invalid once nginx reload loads the configurations from the configed folder. Any Nginx configurations that need to be retained must be saved by executing write on the device.

Nginx Accessing Different Partitions

Since the ET2500 device operates on the eMMC partition, users can access local resources by specifying files within /etc/sonic/nginx_mmc. If a user connects a removable USB drive or an NVMe hard drive to the device, they must mount the partition on the device:

sudo mount --make-rshared /etc/sonic/nginx_sda
sudo mount /dev/sda1 /etc/sonic/nginx_sda

After mounting the partition, a device reload is required for the changes to take effect. If the device is rebooted or undergoes a version upgrade, the mounted partition will become invalid. You will need to remount it and perform the reload again (please note this refers to a device reload, not an nginx reload).

Modify queue cache size

For modifying the queue cache size related to nginx, you can modify the vcl.conf file in the/etc/sonic/nginx/conf path:

vcl {
  heapsize 2G                                   #The memory heap size allocated for VCL, 2GB (for storing data buffers, etc.)
  segment-size 1073741824         #The size of each shared memory segment, 1GB (1073741824 bytes),
used for VCL and VPP communication
  add-segment-size 268435456    #When it is necessary to dynamically add new shared memory segments, the size of
each new segment is 256MB
  rx-fifo-size 16777216   #Receive FIFO buffer size, 16MB (for receiving data from VPP)
  tx-fifo-size 16777216    #Send FIFO buffer size, default 16MB (for sending data to VPP), adjustable size
  api-socket-name /var/run/vpp/api.sock

  app-scope-local
  app-scope-global
  use-mq-eventfd

  event-queue-size 1000000
}

After the file modification is completed, the device needs to perform a reload to take effect.

Nginx Configuration

Global Nginx Switch

Operation	Command	Description
Enter the system configuration view	configure terminal
Global Enable Nginx	nginx enable
Global Disable Nginx	nginx stop

Configuring Nginx/vpp Core Count

Operation	Command	Description
Enter the system configuration view	configure terminal
Configuring Nginx/vpp Core Count	cpu_core {nginx_num string1|vpp_num string2}	The default number of cores for VPP is 6, and for Nginx, it is 1. The ET2500 device features a total of 8 cores. By default, VPP utilizes the last 6 cores (core indices 2-7), while Nginx uses the first core (core index 0). The recommended configuration is to set vpp_num to 3 and nginx_num to 3. Note: For the ET2500 model, ensure that nginx_num + vpp_num ≤ 8. Additionally, please be aware of the  activation requirements: changes to the Nginx core count require an nginx reload to take effect, whereas changes to the VPP core count require you to execute write to save the configuration followed by a device reload.
Reload Nginx configuration	nginx reload	Reload Configuration: This action is required whenever Nginx configurations are modified. This includes scenarios such as uploading new configuration files via update, adjusting global parameters, changing the core count, or deleting related configuration files. Essentially, you must execute nginx reload after any configuration change to apply the new settings.

Nginx Global Parameter Configuration

Operation	Command	Description
Enter the system configuration view	configure terminal
Configure Nginx to maintain timeout for TCP connections	nginx keepalive_timeout time	After configuration, execute nginx reload to successfully load it.
Configure the maximum number of connections that each Nginx worker process can open simultaneously	nginx worker_connections num	After configuration, execute nginx reload to successfully load it.

Loading/Deleting Nginx Configuration Files

Operation	Command	Description
Enter the system configuration view	configure terminal
Nginx updates certificate file/server configuration file	nginx update {cert|server} string	After configuration, execute nginx reload to successfully load it.

Display and Maintenance

Operation	Command	Description
Enter the system view	show nginx status	View nginx enabled status and the number of cores used by nginx
Enter the system view	show nginx config	Display the global parameter configuration results and configuration file loading status of nginx

Nginx Configuration Example

Network Requirements

A certain company needs to provide nginx services for export, which facilitates users to access other partition resources or reverse proxy to backend servers through devices. Users can load and use nginx services through specified server configuration files according to their needs.

Procedure

#Enable Nginx functionality
sonic(config)# nginx start
sonic(config)# cpu_core vpp_num 3 nginx_num 3
sonic(config)# nginx keepalive_timeout 80
sonic(config)# nginx worker_connections 1500
sonic(config)# nginx update server /home/admin/nginx_test1.conf
sonic(config)# nginx reload
#Three layer interface configuration, users can configure themselves according to the network to enable nginx services to
be accessed by clients normally
sonic(config)# interface ethernet 10
 sonic(config-if-10)#ip address 17.1.1.2/24
sonic(config)# interface ethernet 15
 sonic(config-if-15)#ip address 19.1.1.2/24