diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/guix.texi | 249 |
1 files changed, 249 insertions, 0 deletions
diff --git a/doc/guix.texi b/doc/guix.texi index 7bce8a567c..4f6973518f 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -36311,6 +36311,255 @@ Extra command line options for @code{nix-service-type}. @end table @end deftp +@cindex Fail2Ban +@subsubheading Fail2Ban service + +@uref{http://www.fail2ban.org/, @code{fail2ban}} scans log files +(e.g. @code{/var/log/apache/error_log}) and bans IP addresses that show +malicious signs -- repeated password failures, attempts to make use of +exploits, etc. + +@code{fail2ban-service-type} service type is provided by the @code{(gnu +services security)} module. + +This service type runs the @code{fail2ban} daemon. It can be configured +in various ways, which are: + +@table @asis +@item Basic configuration +The basic parameters of the Fail2Ban service can be configured via its +@code{fail2ban} configuration, which is documented below. + +@item User-specified jail extensions +The @code{fail2ban-jail-service} function can be used to add new +Fail2Ban jails. + +@item Shepherd extension mechanism +Service developers can extend the @code{fail2ban-service-type} service +type itself via the usual service extension mechanism. +@end table + +@defvr {Scheme Variable} fail2ban-service-type + +This is the type of the service that runs @code{fail2ban} daemon. Below +is an example of a basic, explicit configuration: + +@lisp +(append + (list + (service fail2ban-service-type + (fail2ban-configuration + (extra-jails + (list + (fail2ban-jail-configuration + (name "sshd") + (enabled #t)))))) + ;; There is no implicit dependency on an actual SSH + ;; service, so you need to provide one. + (service openssh-service-type)) + %base-services) +@end lisp +@end defvr + +@deffn {Scheme Procedure} fail2ban-jail-service @var{svc-type} @var{jail} +Extend @var{svc-type}, a @code{<service-type>} object with @var{jail}, a +@code{fail2ban-jail-configuration} object. + +For example: + +@lisp +(append + (list + (service + ;; The 'fail2ban-jail-service' procedure can extend any service type + ;; with a fail2ban jail. This removes the requirement to explicitly + ;; extend services with fail2ban-service-type. + (fail2ban-jail-service + openssh-service-type + (fail2ban-jail-configuration + (name "sshd") + (enabled #t))) + (openssh-configuration ...)))) +@end lisp +@end deffn + +Below is the reference for the different @code{jail-service-type} +configuration records. + +@c The documentation is to be auto-generated via +@c 'generate-documentation'. See at the bottom of (gnu services +@c security). + +@deftp {Data Type} fail2ban-configuration +Available @code{fail2ban-configuration} fields are: + +@table @asis +@item @code{fail2ban} (default: @code{fail2ban}) (type: package) +The @code{fail2ban} package to use. It is used for both binaries and as +base default configuration that is to be extended with +@code{<fail2ban-jail-configuration>} objects. + +@item @code{run-directory} (default: @code{"/var/run/fail2ban"}) (type: string) +The state directory for the @code{fail2ban} daemon. + +@item @code{jails} (default: @code{()}) (type: list-of-fail2ban-jail-configurations) +Instances of @code{<fail2ban-jail-configuration>} collected from +extensions. + +@item @code{extra-jails} (default: @code{()}) (type: list-of-fail2ban-jail-configurations) +Instances of @code{<fail2ban-jail-configuration>} explicitly provided. + +@item @code{extra-content} (type: maybe-string) +Extra raw content to add to the end of the @file{jail.local} file. + +@end table + +@end deftp + +@deftp {Data Type} fail2ban-ignore-cache-configuration +Available @code{fail2ban-ignore-cache-configuration} fields are: + +@table @asis +@item @code{key} (type: string) +Cache key. + +@item @code{max-count} (type: integer) +Cache size. + +@item @code{max-time} (type: integer) +Cache time. + +@end table + +@end deftp + +@deftp {Data Type} fail2ban-jail-action-configuration +Available @code{fail2ban-jail-action-configuration} fields are: + +@table @asis +@item @code{name} (type: string) +Action name. + +@item @code{arguments} (default: @code{()}) (type: list-of-arguments) +Action arguments. + +@end table + +@end deftp + +@deftp {Data Type} fail2ban-jail-configuration +Available @code{fail2ban-jail-configuration} fields are: + +@table @asis +@item @code{name} (type: string) +Required name of this jail configuration. + +@item @code{enabled?} (default: @code{#t}) (type: boolean) +Whether this jail is enabled. + +@item @code{backend} (type: maybe-symbol) +Backend to use to detect changes in the @code{ogpath}. The default is +'auto. To consult the defaults of the jail configuration, refer to the +@file{/etc/fail2ban/jail.conf} file of the @code{fail2ban} package. + +@item @code{max-retry} (type: maybe-integer) +The number of failures before a host get banned (e.g. @code{(max-retry +5)}). + +@item @code{max-matches} (type: maybe-integer) +The number of matches stored in ticket (resolvable via tag +@code{<matches>}) in action. + +@item @code{find-time} (type: maybe-string) +The time window during which the maximum retry count must be reached for +an IP address to be banned. A host is banned if it has generated +@code{max-retry} during the last @code{find-time} seconds (e.g. +@code{(find-time "10m")}). It can be provided in seconds or using +Fail2Ban's "time abbreviation format", as described in @command{man 5 +jail.conf}. + +@item @code{ban-time} (type: maybe-string) +The duration, in seconds or time abbreviated format, that a ban should +last. (e.g. @code{(ban-time "10m")}). + +@item @code{ban-time-increment?} (type: maybe-boolean) +Whether to consider past bans to compute increases to the default ban +time of a specific IP address. + +@item @code{ban-time-factor} (type: maybe-string) +The coefficient to use to compute an exponentially growing ban time. + +@item @code{ban-time-formula} (type: maybe-string) +This is the formula used to calculate the next value of a ban time. + +@item @code{ban-time-multipliers} (type: maybe-string) +Used to calculate next value of ban time instead of formula. + +@item @code{ban-time-max-time} (type: maybe-string) +The maximum number of seconds a ban should last. + +@item @code{ban-time-rnd-time} (type: maybe-string) +The maximum number of seconds a randomized ban time should last. This +can be useful to stop ``clever'' botnets calculating the exact time an +IP address can be unbanned again. + +@item @code{ban-time-overall-jails?} (type: maybe-boolean) +When true, it specifies the search of an IP address in the database +should be made across all jails. Otherwise, only the current jail of +the ban IP address is considered. + +@item @code{ignore-self?} (type: maybe-boolean) +Never ban the local machine's own IP address. + +@item @code{ignore-ip} (default: @code{()}) (type: list-of-strings) +A list of IP addresses, CIDR masks or DNS hosts to ignore. +@code{fail2ban} will not ban a host which matches an address in this +list. + +@item @code{ignore-cache} (type: maybe-fail2ban-ignore-cache-configuration) +Provide cache parameters for the ignore failure check. + +@item @code{filter} (type: maybe-fail2ban-jail-filter-configuration) +The filter to use by the jail, specified via a +@code{<fail2ban-jail-filter-configuration>} object. By default, jails +have names matching their filter name. + +@item @code{log-time-zone} (type: maybe-string) +The default time zone for log lines that do not have one. + +@item @code{log-encoding} (type: maybe-symbol) +The encoding of the log files handled by the jail. Possible values are: +@code{'ascii}, @code{'utf-8} and @code{'auto}. + +@item @code{log-path} (default: @code{()}) (type: list-of-strings) +The file names of the log files to be monitored. + +@item @code{action} (default: @code{()}) (type: list-of-fail2ban-jail-actions) +A list of @code{<fail2ban-jail-action-configuration>}. + +@item @code{extra-content} (type: maybe-string) +Extra content for the jail configuration. + +@end table + +@end deftp + +@deftp {Data Type} fail2ban-jail-filter-configuration +Available @code{fail2ban-jail-filter-configuration} fields are: + +@table @asis +@item @code{name} (type: string) +Filter to use. + +@item @code{mode} (type: maybe-string) +Mode for filter. + +@end table + +@end deftp + +@c End of auto-generated fail2ban documentation. + @node Setuid Programs @section Setuid Programs |