Skip to content

Configuration File

Jump to bottom
Hamza Haddani edited this page May 27, 2023 · 7 revisions

Webserv Configuration File

The Webserv configuration file is a text file used to specify virtual hosts, their document roots, and other settings. The configuration file follows a syntax similar to that of nginx. While it's not mandatory to use a specific extension for the config file, it is recommended to use the .conf file extension for clarity.

Comments

Comments in the configuration file start with a # character and continue until the end of the line. Comments can be placed anywhere in the configuration file, but they cannot be placed at the end of a directive line. For example, the following line is valid:

# This comment takes the whole line, hence it's valid

But the following line is invalid:

listen 8080 # But this comment is invalid

Directives

All directives in the configuration file follow this format: Directive name followed by whitespace or tabs, and then the directive value. The Webserv configuration file primarily consists of server block directives.

Server Block Directives

The server block can include the following directives:

listen

Specifies the host and port to listen on. If no host is specified, the server will listen on all available interfaces. If no port is specified, the server will listen on port 8080. If no listen directive is provided for a sever block, the server will listen on all available interfaces on port 8080.

  • Syntax: listen [host]:[port]
  • Can be specified multiple times: Yes
  • Default values:
    • Host: 0.0.0.0 (Listens on all available interfaces)
    • Port: 8080

server_name

Defines the server name (Multiple values can be separated by spaces).

  • Syntax: server_name [name_1] [name_2] ...
  • Can be specified multiple times: Yes
  • Default value: The first listen directive value (E.g. localhost:8080)

client_max_body_size

Sets the maximum size limit for the body of a client request. If the body of a request exceeds this limit, the server will return a 413 (Payload too large) error. The value can be specified in bytes, kilobytes, or megabytes by appending b, k, or m to the value. If no suffix is provided, the value is assumed to be in bytes.

  • Syntax: client_max_body_size [size]
  • Can be specified multiple times: No
  • Default value: 1m (1 megabyte)

error_pages

This block-level directive maps error codes to their corresponding error page paths. If an error code is not specified, there is an appropriate error page builtin to the server that will be used instead. The error page paths are relative to the server root. If multiple error pages are specified for the same error code, the first one will be used.

  • Syntax: error_pages [error_code] [path1] [path2] ...
  • Can be specified multiple times: No
  • Default value: None

location

Defines a specific route or a URL path within the server. If no location is specified for a certain server, a default / location is created.

  • Syntax: location [path] { ... }
  • Can be specified multiple times: Yes
  • Default value: None

Example

server {
    listen 127.0.0.1:80
    server_name foo bar baz

    client_max_body_size 10m

    error_pages {
        400 /400.html
        404 /404.html
        500 501 502 /50x.html
    }

    location /foo {
        ...
    }
}

server {
    ...
}

...

Location Block Directives

The following directives can be used within a location block:

allowed_methods

Specifies the list of HTTP methods that a client can use to interact with a server at a specific location. The methods implemented in Webserv are GET, POST, PUT, and DELETE. If a client uses a method that is not specified in this directive, the server will return a 405 (Method not allowed) error. If no allowed_methods directive is provided, the server will only allow GET requests on that location.

  • Syntax: allowed_methods [method1] [method2] ...
  • Can be specified multiple times: No
  • Default value: GET

root

Defines the document root for a specific location. The document root is the directory from which the server will serve files in response to requests. The path is relative to the server root.

  • Syntax: root [path]
  • Can be specified multiple times: No
  • Default value: html directory on the project root

index

Defines the list of files that the server will look for in the document root if the client requests a directory. If the client requests a directory and none of the files specified in the index directive are found, the server will return a 403 (Forbidden) error.

  • Syntax: index [file1] [file2] ...
  • Can be specified multiple times: No
  • Default value: none

autoindex

Enables/Disables directory listing for a specific location. If enabled, the server will return a list of files in the directory if the client requests a directory and none of the files specified in the index directive are found. If disabled, the server will return a 403 (Forbidden) error if the client requests a directory and none of the files specified in the index directive are found.

  • Syntax: autoindex [on|off]
  • Can be specified multiple times: No
  • Default value: off

cgi

This block-level directive defines a set of CGI file extensions with their corresponding CGI interpreters. The interpreter can be an absolute path or it can be the name only if the interpreter is accessible via PATH environment variable. If multiple CGI directives are specified for the same file extension, the last one will be used.

  • Syntax: cgi { [file_extension] [interpreter] }
  • Can be specified multiple times: No
  • Default value: None

Configuration Example

Here is an example configuration file using all the directives mentioned above.

server {
    listen localhost:8080
    server_name localhost

    client_max_body_size 42m

    error_pages {
        400 /400.html
        404 /404.html
        500 501 502 /50x.html
    }

    location /foo {
        root /var/www/html
        index index.html index.php index.py
        autoindex on

        cgi {
            php /usr/bin/php-cgi
            py /usr/bin/python3
        }
    }

    location /bar {
        root /usr/share/html
        index index.html index.htm
        autoindex off

        allowed_methods GET POST DELETE
    }
}

Minimum configuration

The configuration must have at least one server block. It can be an empty block, but it must be present.

Clone this wiki locally