Next: , Previous: , Up: Services   [Contents][Index]


6.2.7.14 Web Services

The (gnu services web) module provides the nginx web server and also a fastcgi wrapper daemon.

Scheme Variable: nginx-service-type

Service type for the NGinx web server. The value for this service type is a <nginx-configuration> record.

A simple example configuration is given below.

(service nginx-service-type
         (nginx-configuration
           (server-blocks
             (list (nginx-server-configuration
                     (server-name '("www.example.com"))
                     (root "/srv/http/www.example.com")
                     (https-port #f)
                     (ssl-certificate #f)
                     (ssl-certificate-key #f))))))

In addition to adding server blocks to the service configuration directly, this service can be extended by other services to add server blocks, as in this example:

(simple-service 'my-extra-server nginx-service-type
                (list (nginx-server-configuration
                        (https-port #f)
                        (ssl-certificate #f)
                        (ssl-certificate-key #f)
                        (root "/srv/http/extra-website")
                        (try-files (list "$uri" "$uri/index.html")))))

At startup, nginx has not yet read its configuration file, so it uses a default file to log error messages. If it fails to load its configuration file, that is where error messages are logged. After the configuration file is loaded, the default error log file changes as per configuration. In our case, startup error messages can be found in /var/run/nginx/logs/error.log, and after configuration in /var/log/nginx/error.log. The second location can be changed with the log-directory configuration option.

Data Type: nginx-configuration

This data type represents the configuration for NGinx. Some configuration can be done through this and the other provided record types, or alternatively, a config file can be provided.

nginx (default: nginx)

The nginx package to use.

log-directory (default: "/var/log/nginx")

The directory to which NGinx will write log files.

run-directory (default: "/var/run/nginx")

The directory in which NGinx will create a pid file, and write temporary files.

server-blocks (default: '())

A list of server blocks to create in the generated configuration file, the elements should be of type <nginx-server-configuration>.

The following example would setup NGinx to serve www.example.com from the /srv/http/www.example.com directory, without using HTTPS.

(service nginx-service-type
         (nginx-configuration
           (server-blocks
             (list (nginx-server-configuration
                     (server-name '("www.example.com"))
                     (root "/srv/http/www.example.com")
                     (https-port #f)
                     (ssl-certificate #f)
                     (ssl-certificate-key #f))))))
upstream-blocks (default: '())

A list of upstream blocks to create in the generated configuration file, the elements should be of type <nginx-upstream-configuration>.

Configuring upstreams through the upstream-blocks can be useful when combined with locations in the <nginx-server-configuration> records. The following example creates a server configuration with one location configuration, that will proxy requests to a upstream configuration, which will handle requests with two servers.

(service
  nginx-service-type
  (nginx-configuration
    (server-blocks
      (list (nginx-server-configuration
              (server-name '("www.example.com"))
              (root "/srv/http/www.example.com")
              (https-port #f)
              (ssl-certificate #f)
              (ssl-certificate-key #f)
              (locations
                (list
                  (nginx-location-configuration
                  (uri "/path1")
                  (body '("proxy_pass http://server-proxy;"))))))))
    (upstream-blocks
      (list (nginx-upstream-configuration
              (name "server-proxy")
              (servers (list "server1.example.com"
                             "server2.example.com")))))))
file (default: #f)

If a configuration file is provided, this will be used, rather than generating a configuration file from the provided log-directory, run-directory, server-blocks and upstream-blocks. For proper operation, these arguments should match what is in file to ensure that the directories are created when the service is activated.

This can be useful if you have an existing configuration file, or it’s not possible to do what is required through the other parts of the nginx-configuration record.

Data Type: nginx-server-configuration

Data type representing the configuration of an nginx server block. This type has the following parameters:

http-port (default: 80)

Nginx will listen for HTTP connection on this port. Set it at #f if nginx should not listen for HTTP (non secure) connection for this server block.

https-port (default: 443)

Nginx will listen for HTTPS connection on this port. Set it at #f if nginx should not listen for HTTPS (secure) connection for this server block.

Note that nginx can listen for HTTP and HTTPS connections in the same server block.

server-name (default: (list 'default))

A list of server names this server represents. 'default represents the default server for connections matching no other server.

root (default: "/srv/http")

Root of the website nginx will serve.

locations (default: '())

A list of nginx-location-configuration or nginx-named-location-configuration records to use within this server block.

index (default: (list "index.html"))

Index files to look for when clients ask for a directory. If it cannot be found, Nginx will send the list of files in the directory.

try-files (default: '())

A list of files whose existence is checked in the specified order. nginx will use the first file it finds to process the request.

ssl-certificate (default: "/etc/nginx/cert.pem")

Where to find the certificate for secure connections. Set it to #f if you don’t have a certificate or you don’t want to use HTTPS.

ssl-certificate-key (default: "/etc/nginx/key.pem")

Where to find the private key for secure connections. Set it to #f if you don’t have a key or you don’t want to use HTTPS.

server-tokens? (default: #f)

Whether the server should add its configuration to response.

Data Type: nginx-upstream-configuration

Data type representing the configuration of an nginx upstream block. This type has the following parameters:

name

Name for this group of servers.

servers

Specify the addresses of the servers in the group. The address can be specified as a IP address (e.g. ‘127.0.0.1’), domain name (e.g. ‘backend1.example.com’) or a path to a UNIX socket using the prefix ‘unix:’. For addresses using an IP address or domain name, the default port is 80, and a different port can be specified explicitly.

Data Type: nginx-location-configuration

Data type representing the configuration of an nginx location block. This type has the following parameters:

uri

URI which this location block matches.

body

Body of the location block, specified as a string. This can contain many configuration directives. For example, to pass requests to a upstream server group defined using an nginx-upstream-configuration block, the following directive would be specified in the body ‘proxy_pass http://upstream-name;’.

Data Type: nginx-named-location-configuration

Data type representing the configuration of an nginx named location block. Named location blocks are used for request redirection, and not used for regular request processing. This type has the following parameters:

name

Name to identify this location block.

body

See nginx-location-configuration body, as the body for named location blocks can be used in a similar way to the nginx-location-configuration body. One restriction is that the body of a named location block cannot contain location blocks.

FastCGI is an interface between the front-end and the back-end of a web service. It is a somewhat legacy facility; new web services should generally just talk HTTP between the front-end and the back-end. However there are a number of back-end services such as PHP or the optimized HTTP Git repository access that use FastCGI, so we have support for it in Guix.

To use FastCGI, you configure the front-end web server (e.g., nginx) to dispatch some subset of its requests to the fastcgi backend, which listens on a local TCP or UNIX socket. There is an intermediary fcgiwrap program that sits between the actual backend process and the web server. The front-end indicates which backend program to run, passing that information to the fcgiwrap process.

Scheme Variable: fcgiwrap-service-type

A service type for the fcgiwrap FastCGI proxy.

Data Type: fcgiwrap-configuration

Data type representing the configuration of the fcgiwrap serice. This type has the following parameters:

package (default: fcgiwrap)

The fcgiwrap package to use.

socket (default: tcp:127.0.0.1:9000)

The socket on which the fcgiwrap process should listen, as a string. Valid socket values include unix:/path/to/unix/socket, tcp:dot.ted.qu.ad:port and tcp6:[ipv6_addr]:port.

user (default: fcgiwrap)
group (default: fcgiwrap)

The user and group names, as strings, under which to run the fcgiwrap process. The fastcgi service will ensure that if the user asks for the specific user or group names fcgiwrap that the corresponding user and/or group is present on the system.

It is possible to configure a FastCGI-backed web service to pass HTTP authentication information from the front-end to the back-end, and to allow fcgiwrap to run the back-end process as a corresponding local user. To enable this capability on the back-end., run fcgiwrap as the root user and group. Note that this capability also has to be configured on the front-end as well.


Next: , Previous: , Up: Services   [Contents][Index]