Next: Certificate Services, Previous: LDAP Services, Up: Services [Contents][Index]
The (gnu services web) module provides the Apache HTTP Server,
the nginx web server, and also a fastcgi wrapper daemon.
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
(httpd-configuration
(config
(httpd-config-file
(server-name "www.example.com")
(document-root "/srv/http/www.example.com")))))
Other services can also extend the httpd-service-type to add to
the configuration.
(simple-service 'www.example.com-server httpd-service-type
(list
(httpd-virtualhost
"*:80"
(list (string-join '("ServerName www.example.com"
"DocumentRoot /srv/http/www.example.com")
"\n")))))
The details for the httpd-configuration, httpd-module,
httpd-config-file and httpd-virtualhost record types are
given below.
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.
This data type represents a module for the httpd service.
nameThe name of the module.
fileThe 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/mod_wsgi.so").
A default list of httpd-module objects.
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 (httpd-configuration (config (httpd-config-file (modules (cons* (httpd-module (name "proxy_module") (file "modules/mod_proxy.so")) (httpd-module (name "proxy_fcgi_module") (file "modules/mod_proxy_fcgi.so")) %default-httpd-modules)) (extra-config (list "\ <FilesMatch \\.php$> SetHandler \"proxy:unix:/var/run/php-fpm.sock|fcgi://localhost/\" </FilesMatch>")))))) (service php-fpm-service-type (php-fpm-configuration (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.
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 'www.example.com-server httpd-service-type
(list
(httpd-virtualhost
"*:80"
(list (string-join '("ServerName www.example.com"
"DocumentRoot /srv/http/www.example.com")
"\n")))))
addresses-and-portsThe addresses and ports for the VirtualHost directive.
contentsThe contents of the VirtualHost directive, this should be a list
of strings and G-expressions.
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"))))))
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.
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 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"))))))
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")
(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.
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:
(modules
(list
(file-append nginx-accept-language-module "\
/etc/nginx/modules/ngx_http_accept_language_module.so")
(file-append nginx-lua-module "\
/etc/nginx/modules/ngx_http_lua_module.so")))
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-resty-lrucache
lua-resty-signal
lua-tablepool
lua-resty-shell))
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.
(global-directives
`((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 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:
'("127.0.0.1:8000" "127.0.0.1" "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 representing the configuration of an nginx upstream
block. This type has the following parameters:
nameName for this group of servers.
serversSpecify 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.
extra-contentAdditional content to be appended to the upstream block. Can be a string or file-like object or list of thereof. In case of list, each item is prefixed with indentation and suffixed with a new line. Nested lists are flattened.
(extra-content "include /etc/nginx/custom-config.conf;") (extra-content `("include /etc/nginx/custom-config.conf;" ("include " ,%custom-config.conf ";")))
Data type representing the configuration of an nginx location
block. This type has the following parameters:
uriURI which this location block matches.
bodyBody 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 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:
nameName to identify this location block.
bodySee 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 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.
Service type for the Varnish daemon.
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 www.gnu.org with VCL you can do something along these lines:
(define %gnu-mirror (plain-file "gnu.vcl" "vcl 4.1; backend gnu { .host = \"www.gnu.org\"; }")) (operating-system ;; … (services (cons (service varnish-service-type (varnish-configuration (listen '(":80")) (vcl %gnu-mirror))) %base-services)))
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 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:
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.
Service type for Whoogle Search. Its value must be a
whoogle-configuration record—see below.
Data type representing Whoogle Search service configuration.
package (default: whoogle-search)The Whoogle Search package to use.
host (default: "127.0.0.1")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.
Service type for Patchwork.
The following example is an example of a minimal service for Patchwork, for
the patchwork.example.com domain.
(service patchwork-service-type
(patchwork-configuration
(domain "patchwork.example.com")
(settings-module
(patchwork-settings-module
(allowed-hosts (list domain))
(default-from-email "patchwork@patchwork.example.com")))
(getmail-retriever-config
(getmail-retriever-configuration
(type "SimpleIMAPSSLRetriever")
(server "imap.example.com")
(port 993)
(username "patchwork")
(password-command
(list (file-append coreutils "/bin/cat")
"/etc/getmail-patchwork-imap-password"))
(extra-parameters
'((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 representing the Patchwork service configuration. This type has the following parameters:
patchwork (default: patchwork)The Patchwork package to use.
domainThe domain to use for Patchwork, this is used in the HTTPD service virtual host.
settings-moduleThe 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.
getmail-retriever-configThe 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 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.
allowed-hostsA 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.
default-from-emailThe 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 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.
This is the service type for Mumi.
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.
mumi-configuration-senderThe email address used as the sender for comments.
mumi-configuration-smtpA 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.
A service type for the fcgiwrap FastCGI proxy.
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: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.
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.
A Service type for php-fpm.
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:
"ip.add.re.ss:port"Listen on a TCP socket to a specific address on a specific port.
"port"Listen on a TCP socket to all addresses on a specific port.
"/path/to/unix/socket"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)) "-fpm.pid"))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:
<php-fpm-dynamic-process-manager-configuration><php-fpm-static-process-manager-configuration><php-fpm-on-demand-process-manager-configuration>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")) (operating-system ;; … (services (cons (service php-fpm-service-type (php-fpm-configuration (php-ini-file %local-php-ini))) %base-services)))
Consult the core php.ini directives for comprehensive documentation on the acceptable php.ini directives.
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 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 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.
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
(nginx-server-configuration
(server-name '("example.com"))
(root "/srv/http/")
(locations
(list (nginx-php-location)))
(listen '("80"))
(ssl-certificate #f)
(ssl-certificate-key #f)))
%base-services))
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.
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
#:configuration
(nginx-server-configuration
(server-name '("example.com"))))
...
%base-services))
The hpcguix-web program is a customizable web interface to browse Guix packages, initially designed for users of high-performance computing (HPC) clusters.
The service type for hpcguix-web.
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: "127.0.0.1")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
(hpcguix-web-configuration
(specs
#~(hpcweb-configuration
(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.
This is the type of the gmnisrv service, whose value should be a
gmnisrv-configuration object, as in this example:
(service gmnisrv-service-type
(gmnisrv-configuration
(config-file (local-file "./my-gmnisrv.ini"))))
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.
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
(agate-configuration
(content "/srv/gemini")
(certificates "/srv/gemini-certs")))
The example above represents the minimal tweaking necessary to get Agate up and running. Specifying the path to the certificate and key directory is always necessary, as the Gemini protocol requires TLS by default.
If the specified certificates path is writable by Agate, and contains
no valid pre-generated key and certificate, Agate will try to generate
them on the first start. In this case you should pass at least one
hostname using the hostnames option.
If the specified directory is read-only, key and certificate should be
pre-generated by the user.
To obtain a certificate and a key in DER format, you could, for example, use OpenSSL, running commands similar to the following example:
openssl genpkey -out key.der -outform DER -algorithm RSA \
-pkeyopt rsa_keygen_bits:4096
openssl req -x509 -key key.der -outform DER -days 3650 -out cert.der \
-subj "/CN=example.com"
Of course, you’ll have to replace example.com with your own domain
name, and then point the Agate configuration towards the path of the
directory with the generated key and certificate using the certificates option.
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.
certificates (default: "/srv/gemini-certs")Root of the certificate directory. Must be filled in with a value from the user.
addresses (default: '("[::]:1965" "0.0.0.0:1965"))A list of the addresses to listen on.
hostnames (default: '())Virtual hosts for the Gemini server. If multiple values are
specified, corresponding directory names should be present in the content
directory. Optional.
languages (default: #f)RFC 4646 language code(s) for text/gemini documents. Optional.
only-tls13? (default: #f)Set to #t to disable support for TLSv1.2.
serve-secret? (default: #f)Set to #t to serve secret files (files/directories starting with
a dot).
central-configuration? (default: #f)Set to #t to look for the .meta configuration file in the content
root directory and will ignore .meta files in other directories
ed25519? (default: #f)Set to #t to generate keys using the Ed25519 signature algorithm
instead of the default ECDSA.
skip-port-check? (default: #f)Set to #t to skip URL port check even when a hostname is specified.
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]