Logo
CAR REVIEW
Windows Vista
Windows 7
Windows Azure
Windows Server
Windows Phone
PREGNANCY
 
 
Windows Server

Nginx HTTP Server : Basic Nginx Configuration - Base module directives

3/17/2013 11:36:32 AM

In this section, we will take a closer look at the base modules. We are particularly interested in answering two questions what are base modules and what directives are made available.

What are base modules?

The base modules offer directives that allow you to define parameters of the basic functionality of Nginx. They cannot be disabled at compile time; as a result, the directives and blocks they offer are always available. Three base modules are distinguished:

  • Core module: Essential features and directives such as process management and security

  • Events module: It lets you configure the inner mechanisms of the networking capabilities

  • Configuration module: Enables the inclusion mechanism

These modules offer a large range of directives; we will be detailing them individually with their syntaxes and default values.

Nginx process architecture

Before we start detailing the basic configuration directives, it's necessary to understand the process architecture, that is, how Nginx works behind the scenes. Although the application comes as a simple binary file, (apparently lightweight background process) the way it functions at runtime is rather intricate.

At the very moment of starting Nginx, one unique process exists in memory the Master Process. It is launched with the current user and group permissions usually root/root if the service is launched at boot time by an init script. The master process itself does not process any client request; instead, it spawns processes that do the Worker Processes, which are affected to a customizable user and group. From the configuration file, you are able to define the amount of worker processes, the maximum connections per worker process, and more.

Core module directives

Below is the list of directives made available by the Core module. Most of these directives must be placed at the root of the configuration file and can only be used once. However, some of them are valid in multiple contexts. If that is the case, the list of valid contexts is mentioned below the directive name.root of the configuration file and can only be used once.

Name and context Syntax and description
daemon Accepted values: on or off

Syntax:

daemon on;

Default value: on

Enables or disables daemon mode. If you disable it, the program will not be started in the background; it will stay in the foreground when launched from the shell.
debug_points Accepted values: stop or abort

Syntax:

debug_points stop;

Default value: None.

Activates debug points in Nginx. Use stop to interrupt the application when a debug point comes about in order to attach a debugger. Use abort to abort the debug point and create a core dump file.

To disable this option, simply do not use the directive.
env Syntax:

env MY_VARIABLE;

env MY_VARIABLE=my_value;

Lets you (re)define environment variables.
error_log Context: main, http, server, and location Syntax:

error_log /file/path level;

Default value: logs/error.log error.

Where level is one of the following values: debug, info, notice, warn, error, and crit (from most to least detailed: debug provides frequent log entries, crit only reports critical errors).

Enables error logging at different levels: Application, HTTP server, virtual host, and virtual host directory.

By redirecting the log output to /dev/null, you can disable error logging. Use the following directive at the root of the configuration file:

error_log /dev/null crit;
lock_file Syntax: File path

lock_file logs/nginx.lock;

Default value: Defined at compile time

Use a lock file for mutual exclusion. Disabled by default, unless you enabled it at compile time.
log_not_found Context: main, http, server, and location Accepted values: on or off

log_not_found on;

Default value: on

Enables or disables logging of 404 not found HTTP errors. If your logs get filled with 404 errors due to missing favicon.ico or robots.txt files, you might want to turn this off.
master_process Accepted values: on or off

master_process on;

Default value: on

If enabled, Nginx will start multiple processes: A main process (the master process) and worker processes. If disabled, Nginx works with a unique process. This directive should be used for testing purposes only as it disables the master process clients thus cannot connect to your server.
pid Syntax: File path

pid logs/nginx.pid;

Default value: Defined at compile time.

Path of the pid file for the Nginx daemon. The default value can be configured at compile time.
ssl_engine Syntax: Character string

ssl_engine enginename;

Default value: None

Where enginename is the name of an available hardware SSL accelerator on your system. To check for available hardware SSL accelerators, run this command from the shell:

openssl engine -t
thread_stack_size Syntax: Numeric (size)

thread_stack_size 1m;

Default value: None

Defines the size of thread stack; please refer to the worker_threads directive below
timer_resolution Syntax: Numeric (time)

timer_resolution 100ms;

Default value: None

Controls the interval between system calls to gettimeofday() to synchronize the internal clock. If this value is not specified, the clock is refreshed after each kernel event notification.
user Syntax:

user username groupname;

user username;

Default value: Defined at compile time. If still undefined, the user and group of the Nginx master process are used.

Lets you define the user account and optionally the user group used for starting the Nginx worker processes.
worker_threads Syntax: Numeric

worker_threads 8;

Default value: None

Defines the amount of threads per worker process.

Warning! Threads are disabled by default. The author stated that "the code is currently broken".
worker_cpu_affinity Syntax:

worker_cpu_affinity 1000 0100 0010 0001;

worker_cpu_affinity 10 10 01 01;

worker_cpu_affinity;

Default value: None

This directive works in conjunction with worker_processes. It lets you affect worker processes to CPU cores.

There are as many series of digit blocks as worker processes; there are as many digits in a block as your CPU has cores.

If you configure Nginx to use three worker processes, there are three blocks of digits. For a dual-core CPU, each block has two digits.

worker_cpu_affinity 01 01 10;

The first block (01) indicates that the first worker process should be affected to the second core.

The second block (01) indicates that the second worker process should be affected to the second core.

The third block (10) indicates that the third worker process should be affected to the first core.

Note that affinity is only recommended for multi-core CPUs, not for processors with hyper-treading or similar technologies.
worker_priority Syntax: Numeric

worker_priority 0;

Default value: 0

Defines the priority of the worker processes, from -20 (highest) to 19 (lowest). The default value is 0. Note that kernel processes run at priority level -5, so it's not recommended that you set the priority to -5 or less.
worker_processes Syntax: Numeric

worker_processes 4;

Default value: 1

Defines the amount of worker processes. Nginx offers to separate the treatment of requests into multiple processes. The default value is 1, but it's recommended to increase this value if your CPU has more than one core.

Besides, if a process gets blocked due to slow I/O operations, incoming requests can be delegated to the other worker processes.
worker_rlimit_core Syntax: Numeric (size)

worker_rlimit_core 100m;

Default value: None

Defines the size of core files per worker process.
worker_rlimit_nofile Syntax: Numeric

worker_rlimit_nofile 10000;

Default value: None

Defines the amount of files a worker process may use simultaneously.
worker_rlimit_sigpending Syntax: Numeric

worker_rlimit_sigpending 10000;

Default value: None

Defines the amount of signals that can be queued per user (user ID of the calling process). If the queue is full, signals are ignored past this limit.
working_directory Syntax: Directory path

working_directory /usr/local/nginx/;

Default value: The prefix switch defined at compile time.

Working directory used for worker processes; only used to define the location of core files. The worker process user account (user directive) must have write permissions on this folder in order to be able to write core files.

Events module

The Events module comes with directives that allow you to configure network mechanisms. Some of the parameters have an important impact on the application's performance.

All of the directives listed below must be placed in the events block, which is located at the root of the configuration file:

user nginx nginx;
    master_process on;
    worker_processes 4;
    events
    worker_connections 1024;
    use epoll;
    }
    [...]

These directives cannot be placed elsewhere (if you do so, the configuration test will fail).

Directive name Syntax and description
accept_mutex Accepted values: on or off

accept_mutex on;

Default value: on

Enables or disables the use of an accept mutex (mutual exclusion) to open listening sockets.
accept_mutex_delay Syntax: Numeric (time)

accept_mutex_delay 500ms;

Default value: 500 milliseconds

Defines the amount of time a worker process should wait before trying to acquire the resource again. This value is not used if the accept_mutex directive is set to off.
connections Replaced by worker_connections. This directive is now deprecated.
debug_connection Syntax: IP address or CIDR block.

debug_connection 172.63.155.21;

debug_connection 172.63.155.0/24;

Default value: None.

Writes detailed logs for clients matching this IP address or address block. The debug information is stored in the file specified with the error_log directive, enabled with the debug level.

Note: Nginx must be compiled with the --debug switch in order to enable this feature.
multi_accept Syntax: on or off

multi_accept off;

Default value: off

Defines whether or not Nginx should accept all incoming connections from the listening queue at once.
use
  • select: The default and standard module, it is used if the OS does not support a more efficient one (it's the only available method under Windows)

  • poll: It is automatically preferred over select, but not available on all systems

  • Accepted values: /dev/poll, epoll, eventport, kqueue, rtsig, or select

  • use kqueue;

  • Default value: Defined at compile time

  • Selects the event model among the available ones (the ones that you enabled at compile time), though Nginx automatically selects the most appropriate one.

  • The supported models are:

kqueue: An efficient method for FreeBSD 4.1+, OpenBSD 2.9+, NetBSD 2.0, and MacOS X operating systems

epoll: An efficient method for Linux 2.6+ based operating systems

rtsig: Real time signals, available as of Linux 2.2.19, but unsuited for high-traffic profiles as default system settings only allow 1,024 queued signals

/dev/poll: An efficient method for Solaris 7 11/99+, HP/UX 11.22+, IRIX 6.5.15+, and Tru64 UNIX 5.1A+ operating systems

eventport: An efficient method for Solaris 10, though a security patch is required
worker_connections Syntax: Numeric

worker_connections 1024;

Default value: None

Defines the amount of connections that a worker process may treat simultaneously.

Configuration module

The Nginx Configuration module is a simple module enabling file inclusions with the include directive, as previously described in the Organization and inclusions section. The directive can be inserted anywhere in the configuration file and accepts a single parameter the file's path.

include /file/path.conf;
    include sites/*.conf;

Note that if you do not specify an absolute path, the file path is relative to the configuration directory. By default, include sites/example.conf will include the following file:

/usr/local/nginx/conf/sites/example.conf.
Other -----------------
- Nginx HTTP Server : Basic Nginx Configuration - Configuration file syntax
- SharePoint 2010 : Configuring Search Settings and the User Interface - Web Parts (part 4)
- SharePoint 2010 : Configuring Search Settings and the User Interface - Web Parts (part 3)
- SharePoint 2010 : Configuring Search Settings and the User Interface - Web Parts (part 2)
- SharePoint 2010 : Configuring Search Settings and the User Interface - Web Parts (part 1)
- Windows Server 2008 R2 file and print services : Administering Print and Document Services (part 2) - Distributed scan server
- Windows Server 2008 R2 file and print services : Administering Print and Document Services (part 1)
- Windows Server 2008 R2 file and print services : Services for Network File System, Windows Search Service
- Windows Server 2008 R2 file and print services : File Server Resource Manager
- Managing Windows Small Business Server 2011 : Adding a Terminal Server (part 3) - Configuring RD Licensing
- Managing Windows Small Business Server 2011 : Adding a Terminal Server (part 2) - Installing the Remote Desktop Services Role
- Managing Windows Small Business Server 2011 : Adding a Terminal Server (part 1)
- Monitoring Dynamics CRM Using System Center Operations Manager (part 3) - Installing the Microsoft Dynamics CRM 4.0 Management Pack
- Monitoring Dynamics CRM Using System Center Operations Manager (part 2) - Microsoft Dynamics CRM Architecture
- Monitoring Dynamics CRM Using System Center Operations Manager (part 1) - SCOM Overview, MOM Versus SCOM
- Microsoft Systems Management Server 2003 : Configuring Software Metering (part 2) - Creating a Software Metering Rule
- Microsoft Systems Management Server 2003 : Configuring Software Metering (part 1) - Configuring the Software Metering Client Agent
- BizTalk Server 2006 : Starting a New BizTalk Project - Creating Your Development Environment
- BizTalk Server 2006 : Starting a New BizTalk Project - Starting Preliminary Design
- Microsoft Content Management Server Development : Validating Placeholder Controls - Validating the SingleAttachmentPlaceholderControl
 
 
Most view of day
- Microsoft Dynamics GP 2010 : Improving performance by adjusting AutoComplete settings, Cleaning up Accounts Receivable with Paid Transaction Removal
- Windows Small Business Server 2011 : Disaster Planning - Planning for Disaster
- Windows Server 2008 : Modifying Accounts with dsmod
- Preparing Windows PE : Automating Windows PE, Using Windows PE with BDD
- Sharepoint 2013 : Backup and Restore (part 5) - Farm Backup and Restore - Performing a Backup
- Deploying the Client for Microsoft Exchange Server 2007 : Planning Considerations and Best Practices, Preparing the Deployment
- Microsoft Exchange Server 2007 : Hub Transport Server Policy Compliance Features (part 4) - Message Classification , Rights Management and the Hub Transport Server
- Using OneNote with Other Programs : OneNote Integration with PowerPoint
- BizTalk Server 2006 : Starting a New BizTalk Project - Starting Preliminary Design
- Windows Server 2003 on HP ProLiant Servers : Logical Structure Design (part 3) - Naming Standards
Top 10
- Windows Phone 8 : Scheduled Tasks - Scheduled Task API Limitations
- Windows Phone 8 : Scheduled Tasks - Updating Tiles Using a Scheduled Task Agent
- Windows Phone 8 : Scheduled Tasks - To-Do List Scheduled Task Sample (part 5) - Editing an Existing To-Do Item
- Windows Phone 8 : Scheduled Tasks - To-Do List Scheduled Task Sample (part 4) - Creating the To-Do Item Shell Tile, Saving a To-Do Item
- Windows Phone 8 : Scheduled Tasks - To-Do List Scheduled Task Sample (part 3) - Debugging Scheduled Tasks
- Windows Phone 8 : Scheduled Tasks - To-Do List Scheduled Task Sample (part 2) - TodoService, TodoItemViewModel
- Windows Phone 8 : Scheduled Tasks - To-Do List Scheduled Task Sample (part 1) - TodoItem,TodoDataContext
- Windows Phone 8 : Scheduled Tasks - Using Scheduled Tasks
- Windows Phone 8 : Scheduled Tasks - Background Agent Types
- Windows Phone 8 : Windows Phone Toolkit Animated Page Transitions - Reusing the Transition Attached Properties
 
 
Windows XP
Windows Vista
Windows 7
Windows Azure
Windows Server
Windows Phone
2015 Camaro