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

11.10.20 Web Services

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

Apache HTTP Server

Variable: httpd-service-type

Service type for the Apache HTTP server (httpd). The value for this service type is a httpd-configuration record.

A simple example configuration is given below.

(service httpd-service-type
               (server-name "")
               (document-root "/srv/http/")))))

Other services can also extend the httpd-service-type to add to the configuration.

(simple-service ' httpd-service-type
                    (list (string-join '("ServerName"
                                         "DocumentRoot /srv/http/")

The details for the httpd-configuration, httpd-module, httpd-config-file and httpd-virtualhost record types are given below.

Data Type: httpd-configuration

This data type represents the configuration for the httpd service.

package (default: httpd)

The httpd package to use.

pid-file (default: "/var/run/httpd")

The pid file used by the shepherd-service.

config (default: (httpd-config-file))

The configuration file to use with the httpd service. The default value is a httpd-config-file record, but this can also be a different G-expression that generates a file, for example a plain-file. A file outside of the store can also be specified through a string.

Data Type: httpd-module

This data type represents a module for the httpd service.


The name of the module.


The file for the module. This can be relative to the httpd package being used, the absolute location of a file, or a G-expression for a file within the store, for example (file-append mod-wsgi "/modules/").

Variable: %default-httpd-modules

A default list of httpd-module objects.

Data Type: httpd-config-file

This data type represents a configuration file for the httpd service.

modules (default: %default-httpd-modules)

The modules to load. Additional modules can be added here, or loaded by additional configuration.

For example, in order to handle requests for PHP files, you can use Apache’s mod_proxy_fcgi module along with php-fpm-service-type:

(service httpd-service-type
            (modules (cons*
                       (name "proxy_module")
                       (file "modules/"))
                       (name "proxy_fcgi_module")
                       (file "modules/"))
            (extra-config (list "\
<FilesMatch \\.php$>
    SetHandler \"proxy:unix:/var/run/php-fpm.sock|fcgi://localhost/\"
(service php-fpm-service-type
          (socket "/var/run/php-fpm.sock")
          (socket-group "httpd")))
server-root (default: httpd)

The ServerRoot in the configuration file, defaults to the httpd package. Directives including Include and LoadModule are taken as relative to the server root.

server-name (default: #f)

The ServerName in the configuration file, used to specify the request scheme, hostname and port that the server uses to identify itself.

This doesn’t need to be set in the server config, and can be specified in virtual hosts. The default is #f to not specify a ServerName.

document-root (default: "/srv/http")

The DocumentRoot from which files will be served.

listen (default: '("80"))

The list of values for the Listen directives in the config file. The value should be a list of strings, when each string can specify the port number to listen on, and optionally the IP address and protocol to use.

pid-file (default: "/var/run/httpd")

The PidFile to use. This should match the pid-file set in the httpd-configuration so that the Shepherd service is configured correctly.

error-log (default: "/var/log/httpd/error_log")

The ErrorLog to which the server will log errors.

user (default: "httpd")

The User which the server will answer requests as.

group (default: "httpd")

The Group which the server will answer requests as.

extra-config (default: (list "TypesConfig etc/httpd/mime.types"))

A flat list of strings and G-expressions which will be added to the end of the configuration file.

Any values which the service is extended with will be appended to this list.

Data Type: httpd-virtualhost

This data type represents a virtualhost configuration block for the httpd service.

These should be added to the extra-config for the httpd-service.

(simple-service ' httpd-service-type
                    (list (string-join '("ServerName"
                                          "DocumentRoot /srv/http/")

The addresses and ports for the VirtualHost directive.


The contents of the VirtualHost directive, this should be a list of strings and G-expressions.


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
             (list (nginx-server-configuration
                     (server-name '(""))
                     (root "/srv/http/"))))))

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
                        (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.

shepherd-requirement (default: '())

This is a list of symbols naming Shepherd services the nginx service will depend on.

This is useful if you would like nginx to be started after a back-end web server or a logging service such as Anonip has been started.

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

The directory to which NGinx will write log files.

log-level (default: 'error) (type: symbol)

Logging level, which can be any of the following values: 'debug, 'info, 'notice, 'warn, 'error, 'crit, 'alert, or 'emerg.

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 from the /srv/http/ directory, without using HTTPS.

(service nginx-service-type
             (list (nginx-server-configuration
                     (server-name '(""))
                     (root "/srv/http/"))))))
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.

      (list (nginx-server-configuration
              (server-name '(""))
              (root "/srv/http/")
                  (uri "/path1")
                  (body '("proxy_pass http://server-proxy;"))))))))
      (list (nginx-upstream-configuration
              (name "server-proxy")
              (servers (list ""
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.

server-names-hash-bucket-size (default: #f)

Bucket size for the server names hash tables, defaults to #f to use the size of the processors cache line.

server-names-hash-bucket-max-size (default: #f)

Maximum bucket size for the server names hash tables.

modules (default: '())

List of nginx dynamic modules to load. This should be a list of file names of loadable modules, as in this example:

  (file-append nginx-accept-language-module "\
  (file-append nginx-lua-module "\
lua-package-path (default: '())

List of nginx lua packages to load. This should be a list of package names of loadable lua modules, as in this example:

(lua-package-path (list lua-resty-core
lua-package-cpath (default: '())

List of nginx lua C packages to load. This should be a list of package names of loadable lua C modules, as in this example:

(lua-package-cpath (list lua-resty-signal))
global-directives (default: '((events . ())))

Association list of global directives for the top level of the nginx configuration. Values may themselves be association lists.

 `((worker_processes . 16)
   (pcre_jit . on)
   (events . ((worker_connections . 1024)))))
extra-content (default: "")

Additional content to be appended to the http block. Can either be a value that can be lowered into a string or a list of such values. In the former case, it is inserted directly. In the latter, it is prefixed with indentation and suffixed with a newline. Nested lists are flattened into one line.

(extra-content "include /etc/nginx/custom-config.conf;")
(extra-content `("include /etc/nginx/custom-config.conf;"
                 ("include " ,%custom-config.conf ";")))
Data Type: nginx-server-configuration

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

listen (default: '("80" "443 ssl"))

Each listen directive sets the address and port for IP, or the path for a UNIX-domain socket on which the server will accept requests. Both address and port, or only address or only port can be specified. An address may also be a hostname, for example:

'("" "" "8000" "*:8000" "localhost:8000")
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: #f)

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: #f)

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.

raw-content (default: '())

A list of strings or file-like objects to be appended to the server block. Each item is prefixed with indentation and suffixed with a new line. Nested lists are flattened.

Data Type: nginx-upstream-configuration

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


Name for this group of servers.


Specify the addresses of the servers in the group. The address can be specified as a IP address (e.g. ‘’), domain name (e.g. ‘’) 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.


A string or list of strings to add to the upstream block.

Data Type: nginx-location-configuration

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


URI which this location block matches.


Body of the location block, specified as a list of strings or file-like objects. Each item is prefixed with indentation and suffixed with a new line. Nested lists are flattened.

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 ‘(list "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 to identify this location block.


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.

Varnish Cache

Varnish is a fast cache server that sits in between web applications and end users. It proxies requests from clients and caches the accessed URLs such that multiple requests for the same resource only creates one request to the back-end.

Variable: varnish-service-type

Service type for the Varnish daemon.

Data Type: varnish-configuration

Data type representing the varnish service configuration. This type has the following parameters:

package (default: varnish)

The Varnish package to use.

name (default: "default")

A name for this Varnish instance. Varnish will create a directory in /var/varnish/ with this name and keep temporary files there. If the name starts with a forward slash, it is interpreted as an absolute directory name.

Pass the -n argument to other Varnish programs to connect to the named instance, e.g. varnishncsa -n default.

backend (default: "localhost:8080")

The backend to use. This option has no effect if vcl is set.

vcl (default: #f)

The VCL (Varnish Configuration Language) program to run. If this is #f, Varnish will proxy backend using the default configuration. Otherwise this must be a file-like object with valid VCL syntax.

For example, to mirror with VCL you can do something along these lines:

(define %gnu-mirror
  (plain-file "gnu.vcl"
              "vcl 4.1;
backend gnu { .host = \"\"; }"))

  ;; …
  (services (cons (service varnish-service-type
                            (listen '(":80"))
                            (vcl %gnu-mirror)))

The configuration of an already running Varnish instance can be inspected and changed using the varnishadm program.

Consult the Varnish User Guide and Varnish Book for comprehensive documentation on Varnish and its configuration language.

listen (default: '("localhost:80"))

List of addresses Varnish will listen on.

storage (default: '("malloc,128m"))

List of storage backends that will be available in VCL.

parameters (default: '())

List of run-time parameters in the form '(("parameter" . "value")).

extra-options (default: '())

Additional arguments to pass to the varnishd process.

Whoogle Search

Whoogle Search is a self-hosted, ad-free, privacy-respecting meta search engine that collects and displays Google search results. By default, you can configure it by adding this line to the services field of your operating system declaration:

(service whoogle-service-type)

As a result, Whoogle Search runs as local Web server, which you can access by opening ‘http://localhost:5000’ in your browser. The configuration reference is given below.

Variable: whoogle-service-type

Service type for Whoogle Search. Its value must be a whoogle-configuration record—see below.

Data Type: whoogle-configuration

Data type representing Whoogle Search service configuration.

package (default: whoogle-search)

The Whoogle Search package to use.

host (default: "")

The host address to run Whoogle on.

port (default: 5000)

The port where Whoogle will be exposed.

environment-variables (default: '())

A list of strings with the environment variables to configure Whoogle. You can consult its environment variables template for the list of available options.


Patchwork is a patch tracking system. It can collect patches sent to a mailing list, and display them in a web interface.

Variable: patchwork-service-type

Service type for Patchwork.

The following example is an example of a minimal service for Patchwork, for the domain.

(service patchwork-service-type
          (domain "")
            (allowed-hosts (list domain))
            (default-from-email "")))
            (type "SimpleIMAPSSLRetriever")
            (server "")
            (port 993)
            (username "patchwork")
             (list (file-append coreutils "/bin/cat")
            '((mailboxes . ("Patches"))))))))

There are three records for configuring the Patchwork service. The <patchwork-configuration> relates to the configuration for Patchwork within the HTTPD service.

The settings-module field within the <patchwork-configuration> record can be populated with the <patchwork-settings-module> record, which describes a settings module that is generated within the Guix store.

For the database-configuration field within the <patchwork-settings-module>, the <patchwork-database-configuration> must be used.

Data Type: patchwork-configuration

Data type representing the Patchwork service configuration. This type has the following parameters:

patchwork (default: patchwork)

The Patchwork package to use.


The domain to use for Patchwork, this is used in the HTTPD service virtual host.


The settings module to use for Patchwork. As a Django application, Patchwork is configured with a Python module containing the settings. This can either be an instance of the <patchwork-settings-module> record, any other record that represents the settings in the store, or a directory outside of the store.

static-path (default: "/static/")

The path under which the HTTPD service should serve the static files.


The getmail-retriever-configuration record value to use with Patchwork. Getmail will be configured with this value, the messages will be delivered to Patchwork.

Data Type: patchwork-settings-module

Data type representing a settings module for Patchwork. Some of these settings relate directly to Patchwork, but others relate to Django, the web framework used by Patchwork, or the Django Rest Framework library. This type has the following parameters:

database-configuration (default: (patchwork-database-configuration))

The database connection settings used for Patchwork. See the <patchwork-database-configuration> record type for more information.

secret-key-file (default: "/etc/patchwork/django-secret-key")

Patchwork, as a Django web application uses a secret key for cryptographically signing values. This file should contain a unique unpredictable value.

If this file does not exist, it will be created and populated with a random value by the patchwork-setup shepherd service.

This setting relates to Django.


A list of valid hosts for this Patchwork service. This should at least include the domain specified in the <patchwork-configuration> record.

This is a Django setting.


The email address from which Patchwork should send email by default.

This is a Patchwork setting.

static-url (default: #f)

The URL to use when serving static assets. It can be part of a URL, or a full URL, but must end in a /.

If the default value is used, the static-path value from the <patchwork-configuration> record will be used.

This is a Django setting.

admins (default: '())

Email addresses to send the details of errors that occur. Each value should be a list containing two elements, the name and then the email address.

This is a Django setting.

debug? (default: #f)

Whether to run Patchwork in debug mode. If set to #t, detailed error messages will be shown.

This is a Django setting.

enable-rest-api? (default: #t)

Whether to enable the Patchwork REST API.

This is a Patchwork setting.

enable-xmlrpc? (default: #t)

Whether to enable the XML RPC API.

This is a Patchwork setting.

force-https-links? (default: #t)

Whether to use HTTPS links on Patchwork pages.

This is a Patchwork setting.

extra-settings (default: "")

Extra code to place at the end of the Patchwork settings module.

Data Type: patchwork-database-configuration

Data type representing the database configuration for Patchwork.

engine (default: "django.db.backends.postgresql_psycopg2")

The database engine to use.

name (default: "patchwork")

The name of the database to use.

user (default: "httpd")

The user to connect to the database as.

password (default: "")

The password to use when connecting to the database.

host (default: "")

The host to make the database connection to.

port (default: "")

The port on which to connect to the database.


Mumi is a Web interface to the Debbugs bug tracker, by default for the GNU instance. Mumi is a Web server, but it also fetches and indexes mail retrieved from Debbugs.

Variable: mumi-service-type

This is the service type for Mumi.

Data Type: mumi-configuration

Data type representing the Mumi service configuration. This type has the following fields:

mumi (default: mumi)

The Mumi package to use.

mailer? (default: #true)

Whether to enable or disable the mailer component.


The email address used as the sender for comments.


A URI to configure the SMTP settings for Mailutils. This could be something like sendmail:///path/to/bin/msmtp or any other URI supported by Mailutils. See SMTP Mailboxes in GNU Mailutils.


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.

Variable: fcgiwrap-service-type

A service type for the fcgiwrap FastCGI proxy.

Data Type: fcgiwrap-configuration

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

package (default: fcgiwrap)

The fcgiwrap package to use.

socket (default: tcp:

The socket on which the fcgiwrap process should listen, as a string. Valid socket values include unix:/path/to/unix/socket, 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.


PHP-FPM (FastCGI Process Manager) is an alternative PHP FastCGI implementation with some additional features useful for sites of any size.

These features include:

... and much more.

Variable: php-fpm-service-type

A Service type for php-fpm.

Data Type: php-fpm-configuration

Data Type for php-fpm service configuration.

php (default: php)

The php package to use.

socket (default: (string-append "/var/run/php" (version-major (package-version php)) "-fpm.sock"))

The address on which to accept FastCGI requests. Valid syntaxes are:


Listen on a TCP socket to a specific address on a specific port.


Listen on a TCP socket to all addresses on a specific port.


Listen on a unix socket.

user (default: php-fpm)

User who will own the php worker processes.

group (default: php-fpm)

Group of the worker processes.

socket-user (default: php-fpm)

User who can speak to the php-fpm socket.

socket-group (default: nginx)

Group that can speak to the php-fpm socket.

pid-file (default: (string-append "/var/run/php" (version-major (package-version php)) ""))

The process id of the php-fpm process is written to this file once the service has started.

log-file (default: (string-append "/var/log/php" (version-major (package-version php)) "-fpm.log"))

Log for the php-fpm master process.

process-manager (default: (php-fpm-dynamic-process-manager-configuration))

Detailed settings for the php-fpm process manager. Must be one of:

display-errors (default #f)

Determines whether php errors and warning should be sent to clients and displayed in their browsers. This is useful for local php development, but a security risk for public sites, as error messages can reveal passwords and personal data.

timezone (default #f)

Specifies php_admin_value[date.timezone] parameter.

workers-logfile (default (string-append "/var/log/php" (version-major (package-version php)) "-fpm.www.log"))

This file will log the stderr outputs of php worker processes. Can be set to #f to disable logging.

file (default #f)

An optional override of the whole configuration. You can use the mixed-text-file function or an absolute filepath for it.

php-ini-file (default #f)

An optional override of the default php settings. It may be any “file-like” object (see file-like objects). You can use the mixed-text-file function or an absolute filepath for it.

For local development it is useful to set a higher timeout and memory limit for spawned php processes. This be accomplished with the following operating system configuration snippet:

(define %local-php-ini
  (plain-file "php.ini"
              "memory_limit = 2G
max_execution_time = 1800"))

  ;; …
  (services (cons (service php-fpm-service-type
                            (php-ini-file %local-php-ini)))

Consult the core php.ini directives for comprehensive documentation on the acceptable php.ini directives.

Data type: php-fpm-dynamic-process-manager-configuration

Data Type for the dynamic php-fpm process manager. With the dynamic process manager, spare worker processes are kept around based on its configured limits.

max-children (default: 5)

Maximum of worker processes.

start-servers (default: 2)

How many worker processes should be started on start-up.

min-spare-servers (default: 1)

How many spare worker processes should be kept around at minimum.

max-spare-servers (default: 3)

How many spare worker processes should be kept around at maximum.

Data type: php-fpm-static-process-manager-configuration

Data Type for the static php-fpm process manager. With the static process manager, an unchanging number of worker processes are created.

max-children (default: 5)

Maximum of worker processes.

Data type: php-fpm-on-demand-process-manager-configuration

Data Type for the on-demand php-fpm process manager. With the on-demand process manager, worker processes are only created as requests arrive.

max-children (default: 5)

Maximum of worker processes.

process-idle-timeout (default: 10)

The time in seconds after which a process with no requests is killed.

Procedure: nginx-php-location [#:nginx-package nginx] [socket (string-append "/var/run/php" (version-major (package-version php)) "-fpm.sock")]

A helper function to quickly add php to an nginx-server-configuration.

A simple services setup for nginx with php can look like this:

(services (cons* (service dhcp-client-service-type)
                 (service php-fpm-service-type)
                 (service nginx-service-type
                           (server-name '(""))
                           (root "/srv/http/")
                            (list (nginx-php-location)))
                           (listen '("80"))
                           (ssl-certificate #f)
                           (ssl-certificate-key #f)))

The cat avatar generator is a simple service to demonstrate the use of php-fpm in Nginx. It is used to generate cat avatar from a seed, for instance the hash of a user’s email address.

Procedure: cat-avatar-generator-service [#:cache-dir "/var/cache/cat-avatar-generator"] [#:package cat-avatar-generator] [#:configuration (nginx-server-configuration)]

Returns an nginx-server-configuration that inherits configuration. It extends the nginx configuration to add a server block that serves package, a version of cat-avatar-generator. During execution, cat-avatar-generator will be able to use cache-dir as its cache directory.

A simple setup for cat-avatar-generator can look like this:

(services (cons* (cat-avatar-generator-service
                    (server-name '(""))))


The hpcguix-web program is a customizable web interface to browse Guix packages, initially designed for users of high-performance computing (HPC) clusters.

Variable: hpcguix-web-service-type

The service type for hpcguix-web.

Data Type: hpcguix-web-configuration

Data type for the hpcguix-web service configuration.

specs (default: #f)

Either #f or a gexp (see G-Expressions) specifying the hpcguix-web service configuration as an hpcguix-web-configuration record. The main fields of that record type are:

title-prefix (default: "hpcguix | ")

The page title prefix.

guix-command (default: "guix")

The guix command to use in examples that appear on HTML pages.

package-filter-proc (default: (const #t))

A procedure specifying how to filter packages that are displayed.

package-page-extension-proc (default: (const '()))

Extension package for hpcguix-web.

menu (default: '())

Additional entry in page menu.

channels (default: %default-channels)

List of channels from which the package list is built (see Channels).

package-list-expiration (default: (* 12 3600))

The expiration time, in seconds, after which the package list is rebuilt from the latest instances of the given channels.

See the hpcguix-web repository for a complete example.

package (default: hpcguix-web)

The hpcguix-web package to use.

address (default: "")

The IP address to listen to.

port (default: 5000)

The port number to listen to.

A typical hpcguix-web service declaration looks like this:

(service hpcguix-web-service-type
              (title-prefix "Guix-HPC - ")
              (menu '(("/about" "ABOUT")))))))

Note: The hpcguix-web service periodically updates the package list it publishes by pulling channels from Git. To that end, it needs to access X.509 certificates so that it can authenticate Git servers when communicating over HTTPS, and it assumes that /etc/ssl/certs contains those certificates.

A certificate package, nss-certs, is provided by default as part of %base-packages. X.509 Certificates, for more information on X.509 certificates.


The gmnisrv program is a simple Gemini protocol server.

Variable: gmnisrv-service-type

This is the type of the gmnisrv service, whose value should be a gmnisrv-configuration object, as in this example:

(service gmnisrv-service-type
           (config-file (local-file "./my-gmnisrv.ini"))))
Data Type: gmnisrv-configuration

Data type representing the configuration of gmnisrv.

package (default: gmnisrv)

Package object of the gmnisrv server.

config-file (default: %default-gmnisrv-config-file)

File-like object of the gmnisrv configuration file to use. The default configuration listens on port 1965 and serves files from /srv/gemini. Certificates are stored in /var/lib/gemini/certs. For more information, run man gmnisrv and man gmnisrv.ini.


The Agate (GitHub page over HTTPS) program is a simple Gemini protocol server written in Rust.

Variable: agate-service-type

This is the type of the agate service, whose value should be an agate-service-type object, as in this example:

(service agate-service-type
	   (content "/srv/gemini")
	   (cert "/srv/cert.pem")
	   (key "/srv/key.rsa")))

The example above represents the minimal tweaking necessary to get Agate up and running. Specifying the path to the certificate and key is always necessary, as the Gemini protocol requires TLS by default.

To obtain a certificate and a key, you could, for example, use OpenSSL, running a command similar to the following example:

openssl req -x509 -newkey rsa:4096 -keyout key.rsa -out cert.pem \
    -days 3650 -nodes -subj "/"

Of course, you’ll have to replace with your own domain name, and then point the Agate configuration towards the path of the generated key and certificate.

Data Type: agate-configuration

Data type representing the configuration of Agate.

package (default: agate)

The package object of the Agate server.

content (default: "/srv/gemini")

The directory from which Agate will serve files.

cert (default: #f)

The path to the TLS certificate PEM file to be used for encrypted connections. Must be filled in with a value from the user.

key (default: #f)

The path to the PKCS8 private key file to be used for encrypted connections. Must be filled in with a value from the user.

addr (default: '("" "[::]:1965"))

A list of the addresses to listen on.

hostname (default: #f)

The domain name of this Gemini server. Optional.

lang (default: #f)

RFC 4646 language code(s) for text/gemini documents. Optional.

silent? (default: #f)

Set to #t to disable logging output.

serve-secret? (default: #f)

Set to #t to serve secret files (files/directories starting with a dot).

log-ip? (default: #t)

Whether or not to output IP addresses when logging.

user (default: "agate")

Owner of the agate process.

group (default: "agate")

Owner’s group of the agate process.

log-file (default: "/var/log/agate.log")

The file which should store the logging output of Agate.

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