NAME
Langertha::Holmgang::Sim::Linux::Nginx - nginx on a simulated Linux server: checking and loading the configuration, answering requests
VERSION
version 0.001
SYNOPSIS
# from the Linux simulator (nginx -t, systemctl reload nginx) and from Sim::Http (curl)
my ( $out, $ok ) = Langertha::Holmgang::Sim::Linux::Nginx::nginx( $dev, [ '-t' ], $ctx );
my $err = Langertha::Holmgang::Sim::Linux::Nginx::service( $dev, 'reload', $ctx ); # undef = loaded
my $res = Langertha::Holmgang::Sim::Linux::Nginx::serve( $state, 'web1', \%req, 'client1', 0 );
DESCRIPTION
nginx 1.22 (Debian 12) as state of a Linux device (cai-platform docs/entwurf-evals.md §3.3). The configuration lives in the device's files (/etc/nginx/nginx.conf with include, links in sites-enabled as files: { link: … }). The service is called nginx. Under nginx:
nginx:
conf: /etc/nginx/nginx.conf # optional
initial: { <path>: "<text>" } # optional: what was loaded at start when the
# file has changed since (untested); null =
# the file did not exist then
loaded: { conf, files: { <path>: "<text>" } } # by the simulator: the loaded configuration
Loaded is what applied at the last start, restart or reload (including certificates and keys); a changed file only takes effect after that. A reload with a broken configuration fails, nginx keeps running with the old one; a restart with a broken configuration leaves nginx stopped.
Check like nginx -t: syntax (;, braces), unknown directives, context (is not allowed here), number of arguments, duplicate directives and locations, listen parameters, duplicate default_server, upstream names (host not found in upstream), proxy_pass with URI in regex locations, unknown variables, certificate and key (Langertha::Holmgang::Sim::Linux::Pki: loadable, matching, encrypted only with ssl_password_file), warning on duplicate server name.
Requests ("serve"): socket from listen (address, port, ssl, default_server), server by server_name (exact, *. wildcard, regex, otherwise default server), certificate by SNI, ssl_protocols, ssl_verify_client with ssl_client_certificate; locations as in nginx (=, longest prefix, ^~, regex in order, nested, @name); rewrite (last, break, redirect, permanent), return (also 444), if with simple conditions, set, map; allow/deny, client_max_body_size; proxy_pass (URI part replaces the location's prefix, upstream with backup/down, next server on error or timeout, 502/504), proxy_set_header (default Host $proxy_host, Connection close), proxy_http_version (WebSocket needs 1.1), proxy_read_timeout; add_header (only 2xx/3xx without always); root/alias/index/try_files with the device's files. As in nginx, proxy_set_header, add_header and allow/deny on one level replace all of those of the higher level.
Built in (unless present as a file): /etc/nginx/mime.types, /etc/nginx/proxy_params, /etc/nginx/fastcgi_params.
parse
my $cfg = parse( reader => sub { $text_or_undef }, glob => sub { @paths }, conf => '/etc/nginx/nginx.conf',
state => $state, dev => $dev );
# { ok => 1, servers, upstreams, maps, http, files, conf_files, warnings } or { error => "…" }
ensure
Captures the loaded configuration on the first command (running service: the files, or nginx.initial).
service
systemctl start|restart|reload nginx: loads the configuration; returns undef or nginx's message.
nginx
The command nginx (-t, -T, -q, -s reload|stop|quit|reopen, -v, -V, -c file, without arguments: start).
serve
nginx's answer to a request (see "request" in Langertha::Holmgang::Sim::Linux::Http), or undef when no running nginx listens on the address and port.
SUPPORT
Issues
Please report bugs and feature requests at https://github.com/Getty/langertha-holmgang/issues.
IRC
Join #langertha on irc.perl.org or message Getty directly.
CONTRIBUTING
Contributions are welcome! Please fork the repository and submit a pull request.
AUTHOR
Torsten Raudssus <torsten@raudssus.de>
COPYRIGHT AND LICENSE
This software is copyright (c) 2026 by Torsten Raudssus <torsten@raudssus.de> https://raudssus.de/.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.