nixos/modules/services/networking/hylafax/options.nix

   1 {
   2   config,
   3   lib,
   4   pkgs,
   5   ...
   6 }:
   7
   8 let
   9
  10   inherit (lib.options) literalExpression mkEnableOption mkOption;
  11   inherit (lib.types)
  12     bool
  13     enum
  14     ints
  15     lines
  16     attrsOf
  17     nonEmptyStr
  18     nullOr
  19     path
  20     str
  21     submodule
  22     ;
  23   inherit (lib.modules) mkDefault mkIf mkMerge;
  24
  25   commonDescr = ''
  26     Values can be either strings or integers
  27     (which will be added to the config file verbatimly)
  28     or lists thereof
  29     (which will be translated to multiple
  30     lines with the same configuration key).
  31     Boolean values are translated to "Yes" or "No".
  32     The default contains some reasonable
  33     configuration to yield an operational system.
  34   '';
  35
  36   configAttrType =
  37     # Options in HylaFAX configuration files can be
  38     # booleans, strings, integers, or list thereof
  39     # representing multiple config directives with the same key.
  40     # This type definition resolves all
  41     # those types into a list of strings.
  42     let
  43       inherit (lib.types)
  44         attrsOf
  45         coercedTo
  46         int
  47         listOf
  48         ;
  49       innerType = coercedTo bool (x: if x then "Yes" else "No") (coercedTo int (toString) str);
  50     in
  51     attrsOf (coercedTo innerType lib.singleton (listOf innerType));
  52
  53   cfg = config.services.hylafax;
  54
  55   modemConfigOptions =
  56     { name, config, ... }:
  57     {
  58       options = {
  59         name = mkOption {
  60           type = nonEmptyStr;
  61           example = "ttyS1";
  62           description = ''
  63             Name of modem device,
  64             will be searched for in {file}`/dev`.
  65           '';
  66         };
  67         type = mkOption {
  68           type = nonEmptyStr;
  69           example = "cirrus";
  70           description = ''
  71             Name of modem configuration file,
  72             will be searched for in {file}`config`
  73             in the spooling area directory.
  74           '';
  75         };
  76         config = mkOption {
  77           type = configAttrType;
  78           example = {
  79             AreaCode = "49";
  80             LocalCode = "30";
  81             FAXNumber = "123456";
  82             LocalIdentifier = "LostInBerlin";
  83           };
  84           description = ''
  85             Attribute set of values for the given modem.
  86             ${commonDescr}
  87             Options defined here override options in
  88             {option}`commonModemConfig` for this modem.
  89           '';
  90         };
  91       };
  92       config.name = mkDefault name;
  93       config.config.Include = [ "config/${config.type}" ];
  94     };
  95
  96   defaultConfig =
  97     let
  98       inherit (config.security) wrapperDir;
  99       inherit (config.services.mail.sendmailSetuidWrapper) program;
 100       mkIfDefault = cond: value: mkIf cond (mkDefault value);
 101       noWrapper = config.services.mail.sendmailSetuidWrapper == null;
 102       # If a sendmail setuid wrapper exists,
 103       # we add the path to the default configuration file.
 104       # Otherwise, we use `false` to provoke
 105       # an error if hylafax tries to use it.
 106       c.sendmailPath = mkMerge [
 107         (mkIfDefault noWrapper "${pkgs.coreutils}/bin/false")
 108         (mkIfDefault (!noWrapper) "${wrapperDir}/${program}")
 109       ];
 110       importDefaultConfig =
 111         file: lib.attrsets.mapAttrs (lib.trivial.const mkDefault) (import file { inherit pkgs; });
 112       c.commonModemConfig = importDefaultConfig ./modem-default.nix;
 113       c.faxqConfig = importDefaultConfig ./faxq-default.nix;
 114       c.hfaxdConfig = importDefaultConfig ./hfaxd-default.nix;
 115     in
 116     c;
 117
 118   localConfig =
 119     let
 120       c.hfaxdConfig.UserAccessFile = cfg.userAccessFile;
 121       c.faxqConfig = lib.attrsets.mapAttrs (lib.trivial.const (v: mkIf (v != null) v)) {
 122         AreaCode = cfg.areaCode;
 123         CountryCode = cfg.countryCode;
 124         LongDistancePrefix = cfg.longDistancePrefix;
 125         InternationalPrefix = cfg.internationalPrefix;
 126       };
 127       c.commonModemConfig = c.faxqConfig;
 128     in
 129     c;
 130
 131 in
 132
 133 {
 134
 135   options.services.hylafax = {
 136
 137     enable = mkEnableOption "HylaFAX server";
 138
 139     autostart = mkOption {
 140       type = bool;
 141       default = true;
 142       example = false;
 143       description = ''
 144         Autostart the HylaFAX queue manager at system start.
 145         If this is `false`, the queue manager
 146         will still be started if there are pending
 147         jobs or if a user tries to connect to it.
 148       '';
 149     };
 150
 151     countryCode = mkOption {
 152       type = nullOr nonEmptyStr;
 153       default = null;
 154       example = "49";
 155       description = "Country code for server and all modems.";
 156     };
 157
 158     areaCode = mkOption {
 159       type = nullOr nonEmptyStr;
 160       default = null;
 161       example = "30";
 162       description = "Area code for server and all modems.";
 163     };
 164
 165     longDistancePrefix = mkOption {
 166       type = nullOr str;
 167       default = null;
 168       example = "0";
 169       description = "Long distance prefix for server and all modems.";
 170     };
 171
 172     internationalPrefix = mkOption {
 173       type = nullOr str;
 174       default = null;
 175       example = "00";
 176       description = "International prefix for server and all modems.";
 177     };
 178
 179     spoolAreaPath = mkOption {
 180       type = path;
 181       default = "/var/spool/fax";
 182       description = ''
 183         The spooling area will be created/maintained
 184         at the location given here.
 185       '';
 186     };
 187
 188     userAccessFile = mkOption {
 189       type = path;
 190       default = "/etc/hosts.hfaxd";
 191       description = ''
 192         The {file}`hosts.hfaxd`
 193         file entry in the spooling area
 194         will be symlinked to the location given here.
 195         This file must exist and be
 196         readable only by the `uucp` user.
 197         See hosts.hfaxd(5) for details.
 198         This configuration permits access for all users:
 199         ```
 200           environment.etc."hosts.hfaxd" = {
 201             mode = "0600";
 202             user = "uucp";
 203             text = ".*";
 204           };
 205         ```
 206         Note that host-based access can be controlled with
 207         {option}`config.systemd.sockets.hylafax-hfaxd.listenStreams`;
 208         by default, only 127.0.0.1 is permitted to connect.
 209       '';
 210     };
 211
 212     sendmailPath = mkOption {
 213       type = path;
 214       example = literalExpression ''"''${pkgs.postfix}/bin/sendmail"'';
 215       # '' ;  # fix vim
 216       description = ''
 217         Path to {file}`sendmail` program.
 218         The default uses the local sendmail wrapper
 219         (see {option}`config.services.mail.sendmailSetuidWrapper`),
 220         otherwise the {file}`false`
 221         binary to cause an error if used.
 222       '';
 223     };
 224
 225     hfaxdConfig = mkOption {
 226       type = configAttrType;
 227       example.RecvqProtection = "0400";
 228       description = ''
 229         Attribute set of lines for the global
 230         hfaxd config file {file}`etc/hfaxd.conf`.
 231         ${commonDescr}
 232       '';
 233     };
 234
 235     faxqConfig = mkOption {
 236       type = configAttrType;
 237       example = {
 238         InternationalPrefix = "00";
 239         LongDistancePrefix = "0";
 240       };
 241       description = ''
 242         Attribute set of lines for the global
 243         faxq config file {file}`etc/config`.
 244         ${commonDescr}
 245       '';
 246     };
 247
 248     commonModemConfig = mkOption {
 249       type = configAttrType;
 250       example = {
 251         InternationalPrefix = "00";
 252         LongDistancePrefix = "0";
 253       };
 254       description = ''
 255         Attribute set of default values for
 256         modem config files {file}`etc/config.*`.
 257         ${commonDescr}
 258         Think twice before changing
 259         paths of fax-processing scripts.
 260       '';
 261     };
 262
 263     modems = mkOption {
 264       type = attrsOf (submodule [ modemConfigOptions ]);
 265       default = { };
 266       example.ttyS1 = {
 267         type = "cirrus";
 268         config = {
 269           FAXNumber = "123456";
 270           LocalIdentifier = "Smith";
 271         };
 272       };
 273       description = ''
 274         Description of installed modems.
 275         At least on modem must be defined
 276         to enable the HylaFAX server.
 277       '';
 278     };
 279
 280     spoolExtraInit = mkOption {
 281       type = lines;
 282       default = "";
 283       example = "chmod 0755 .  # everyone may read my faxes";
 284       description = ''
 285         Additional shell code that is executed within the
 286         spooling area directory right after its setup.
 287       '';
 288     };
 289
 290     faxcron.enable.spoolInit = mkEnableOption ''
 291       purging old files from the spooling area with
 292       {file}`faxcron`
 293       each time the spooling area is initialized
 294     '';
 295     faxcron.enable.frequency = mkOption {
 296       type = nullOr nonEmptyStr;
 297       default = null;
 298       example = "daily";
 299       description = ''
 300         purging old files from the spooling area with
 301         {file}`faxcron` with the given frequency
 302         (see systemd.time(7))
 303       '';
 304     };
 305     faxcron.infoDays = mkOption {
 306       type = ints.positive;
 307       default = 30;
 308       description = ''
 309         Set the expiration time for data in the
 310         remote machine information directory in days.
 311       '';
 312     };
 313     faxcron.logDays = mkOption {
 314       type = ints.positive;
 315       default = 30;
 316       description = ''
 317         Set the expiration time for
 318         session trace log files in days.
 319       '';
 320     };
 321     faxcron.rcvDays = mkOption {
 322       type = ints.positive;
 323       default = 7;
 324       description = ''
 325         Set the expiration time for files in
 326         the received facsimile queue in days.
 327       '';
 328     };
 329
 330     faxqclean.enable.spoolInit = mkEnableOption ''
 331       purging old files from the spooling area with
 332       {file}`faxqclean`
 333       each time the spooling area is initialized
 334     '';
 335     faxqclean.enable.frequency = mkOption {
 336       type = nullOr nonEmptyStr;
 337       default = null;
 338       example = "daily";
 339       description = ''
 340         Purge old files from the spooling area with
 341         {file}`faxcron` with the given frequency
 342         (see systemd.time(7)).
 343       '';
 344     };
 345     faxqclean.archiving = mkOption {
 346       type = enum [
 347         "never"
 348         "as-flagged"
 349         "always"
 350       ];
 351       default = "as-flagged";
 352       example = "always";
 353       description = ''
 354         Enable or suppress job archiving:
 355         `never` disables job archiving,
 356         `as-flagged` archives jobs that
 357         have been flagged for archiving by sendfax,
 358         `always` forces archiving of all jobs.
 359         See also sendfax(1) and faxqclean(8).
 360       '';
 361     };
 362     faxqclean.doneqMinutes = mkOption {
 363       type = ints.positive;
 364       default = 15;
 365       example = literalExpression "24*60";
 366       description = ''
 367         Set the job
 368         age threshold (in minutes) that controls how long
 369         jobs may reside in the doneq directory.
 370       '';
 371     };
 372     faxqclean.docqMinutes = mkOption {
 373       type = ints.positive;
 374       default = 60;
 375       example = literalExpression "24*60";
 376       description = ''
 377         Set the document
 378         age threshold (in minutes) that controls how long
 379         unreferenced files may reside in the docq directory.
 380       '';
 381     };
 382
 383   };
 384
 385   config.services.hylafax = mkIf (config.services.hylafax.enable) (mkMerge [
 386     defaultConfig
 387     localConfig
 388   ]);
 389
 390 }