fork/home-manager

git clone https://git.julia.blue/fork/home-manager

Robert HelgessonMerge PR #421575790441

master
34.8 KiB902 linesraw
1# launchd option type from nix-darwin
2#
3# Original Source:
4# https://github.com/LnL7/nix-darwin/blob/14a12e9/modules/launchd/launchd.nix
5
6# Copyright 2017 Daiderd Jordan
7#
8# Permission is hereby granted, free of charge, to any person obtaining
9# a copy of this software and associated documentation files (the "Software"),
10# to deal in the Software without restriction, including without limitation
11# the rights to use, copy, modify, merge, publish, distribute, sublicense,
12# and/or sell copies of the Software, and to permit persons to whom the
13# Software is furnished to do so, subject to the following conditions:
14#
15# The above copyright notice and this permission notice shall be included
16# in all copies or substantial portions of the Software.
17#
18# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
19# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
20# OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
21# IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
22# DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
23# TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE
24# OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
25
26{ config, lib, ... }:
27
28with lib;
29
30{
31  freeformType = with types; attrsOf anything; # added by Home Manager
32
33  options = {
34    Label = mkOption {
35      type = types.str;
36      description = "This required key uniquely identifies the job to launchd.";
37    };
38
39    Disabled = mkOption {
40      type = types.nullOr types.bool;
41      default = null;
42      description = ''
43        This optional key is used as a hint to `launchctl(1)` that it should not submit this job to launchd when
44        loading a job or jobs. The value of this key does NOT reflect the current state of the job on the running
45        system. If you wish to know whether a job is loaded in launchd, reading this key from a configuration
46        file yourself is not a sufficient test. You should query launchd for the presence of the job using
47        the `launchctl(1)` list subcommand or use the ServiceManagement framework's
48        `SMJobCopyDictionary()` method.
49
50        Note that as of Mac OS X v10.6, this key's value in a configuration file conveys a default value, which
51        is changed with the [-w] option of the `launchctl(1)` load and unload subcommands. These subcommands no
52        longer modify the configuration file, so the value displayed in the configuration file is not necessarily
53        the value that `launchctl(1)` will apply. See `launchctl(1)` for more information.
54
55        Please also be mindful that you should only use this key if the provided on-demand and KeepAlive criteria
56        are insufficient to describe the conditions under which your job needs to run. The cost to have a
57        job loaded in launchd is negligible, so there is no harm in loading a job which only runs once or very
58        rarely.
59      '';
60    };
61
62    UserName = mkOption {
63      type = types.nullOr types.str;
64      default = null;
65      description = ''
66        This optional key specifies the user to run the job as. This key is only applicable when launchd is
67        running as root.
68      '';
69    };
70
71    GroupName = mkOption {
72      type = types.nullOr types.str;
73      default = null;
74      description = ''
75        This optional key specifies the group to run the job as. This key is only applicable when launchd is
76        running as root. If UserName is set and GroupName is not, the the group will be set to the default
77        group of the user.
78      '';
79    };
80
81    inetdCompatibility = mkOption {
82      default = null;
83      example = { Wait = true; };
84      description = ''
85        The presence of this key specifies that the daemon expects to be run as if it were launched from inetd.
86      '';
87      type = types.nullOr (types.submodule {
88        options = {
89          Wait = mkOption {
90            type = types.nullOr (types.either types.bool types.str);
91            default = null;
92            description = ''
93              This flag corresponds to the "wait" or "nowait" option of inetd. If true, then the listening
94              socket is passed via the standard in/out/error file descriptors. If false, then `accept(2)` is
95              called on behalf of the job, and the result is passed via the standard in/out/error descriptors.
96            '';
97          };
98        };
99      });
100    };
101
102    LimitLoadToHosts = mkOption {
103      type = types.nullOr (types.listOf types.str);
104      default = null;
105      description = ''
106        This configuration file only applies to the hosts listed with this key. Note: One should set kern.hostname
107        in `sysctl.conf(5)` for this feature to work reliably.
108      '';
109    };
110
111    LimitLoadFromHosts = mkOption {
112      type = types.nullOr (types.listOf types.str);
113      default = null;
114      description = ''
115        This configuration file only applies to hosts NOT listed with this key. Note: One should set kern.hostname
116        in `sysctl.conf(5)` for this feature to work reliably.
117      '';
118    };
119
120    LimitLoadToSessionType = mkOption {
121      type = types.nullOr types.str;
122      default = null;
123      description = ''
124        This configuration file only applies to sessions of the type specified. This key is used in concert
125        with the -S flag to {command}`launchctl`.
126      '';
127    };
128
129    Program = mkOption {
130      type = types.nullOr types.path;
131      default = null;
132      description = ''
133        This key maps to the first argument of `execvp(3)`.  If this key is missing, then the first element of
134        the array of strings provided to the ProgramArguments will be used instead.  This key is required in
135        the absence of the ProgramArguments key.
136      '';
137    };
138
139    ProgramArguments = mkOption {
140      type = types.nullOr (types.listOf types.str);
141      default = null;
142      description = ''
143        This key maps to the second argument of `execvp(3)`.  This key is required in the absence of the Program
144        key. Please note: many people are confused by this key. Please read `execvp(3)` very carefully!
145      '';
146    };
147
148    EnableGlobbing = mkOption {
149      type = types.nullOr types.bool;
150      default = null;
151      description = ''
152        This flag causes launchd to use the `glob(3)` mechanism to update the program arguments before invocation.
153      '';
154    };
155
156    EnableTransactions = mkOption {
157      type = types.nullOr types.bool;
158      default = null;
159      description = ''
160        This flag instructs launchd that the job promises to use `vproc_transaction_begin(3)` and
161        `vproc_transaction_end(3)` to track outstanding transactions that need to be reconciled before the
162        process can safely terminate. If no outstanding transactions are in progress, then launchd is free to
163        send the SIGKILL signal.
164      '';
165    };
166
167    OnDemand = mkOption {
168      type = types.nullOr types.bool;
169      default = null;
170      description = ''
171        This key was used in Mac OS X 10.4 to control whether a job was kept alive or not. The default was
172        true.  This key has been deprecated and replaced in Mac OS X 10.5 and later with the more powerful
173        KeepAlive option.
174      '';
175    };
176
177    KeepAlive = mkOption {
178      type = types.nullOr (types.either types.bool (types.submodule {
179        options = {
180
181          SuccessfulExit = mkOption {
182            type = types.nullOr types.bool;
183            default = null;
184            description = ''
185              If true, the job will be restarted as long as the program exits and with an exit status of zero.
186              If false, the job will be restarted in the inverse condition.  This key implies that "RunAtLoad"
187              is set to true, since the job needs to run at least once before we can get an exit status.
188            '';
189          };
190
191          NetworkState = mkOption {
192            type = types.nullOr types.bool;
193            default = null;
194            description = ''
195              If true, the job will be kept alive as long as the network is up, where up is defined as at least
196              one non-loopback interface being up and having IPv4 or IPv6 addresses assigned to them.  If
197              false, the job will be kept alive in the inverse condition.
198            '';
199          };
200
201          PathState = mkOption {
202            type = types.nullOr (types.attrsOf types.bool);
203            default = null;
204            description = ''
205              Each key in this dictionary is a file-system path. If the value of the key is true, then the job
206              will be kept alive as long as the path exists.  If false, the job will be kept alive in the
207              inverse condition. The intent of this feature is that two or more jobs may create semaphores in
208              the file-system namespace.
209            '';
210          };
211
212          OtherJobEnabled = mkOption {
213            type = types.nullOr (types.attrsOf types.bool);
214            default = null;
215            description = ''
216              Each key in this dictionary is the label of another job. If the value of the key is true, then
217              this job is kept alive as long as that other job is enabled. Otherwise, if the value is false,
218              then this job is kept alive as long as the other job is disabled.  This feature should not be
219              considered a substitute for the use of IPC.
220            '';
221          };
222
223          Crashed = mkOption {
224            type = types.nullOr types.bool;
225            default = null;
226            description = ''
227              If true, the the job will be restarted as long as it exited due to a signal which is typically
228              associated with a crash (SIGILL, SIGSEGV, etc.). If false, the job will be restarted in the
229              inverse condition.
230            '';
231          };
232
233          AfterInitialDemand = mkOption {
234            type = types.nullOr types.bool;
235            default = null;
236          };
237
238        };
239      }));
240      default = null;
241      description = ''
242        This optional key is used to control whether your job is to be kept continuously running or to let
243        demand and conditions control the invocation. The default is false and therefore only demand will start
244        the job. The value may be set to true to unconditionally keep the job alive. Alternatively, a dictionary
245        of conditions may be specified to selectively control whether launchd keeps a job alive or not. If
246        multiple keys are provided, launchd ORs them, thus providing maximum flexibility to the job to refine
247        the logic and stall if necessary. If launchd finds no reason to restart the job, it falls back on
248        demand based invocation.  Jobs that exit quickly and frequently when configured to be kept alive will
249        be throttled to converve system resources.
250      '';
251    };
252
253    RunAtLoad = mkOption {
254      type = types.nullOr types.bool;
255      default = null;
256      description = ''
257        This optional key is used to control whether your job is launched once at the time the job is loaded.
258        The default is false.
259      '';
260    };
261
262    RootDirectory = mkOption {
263      type = types.nullOr types.str;
264      default = null;
265      description = ''
266        This optional key is used to specify a directory to `chroot(2)` to before running the job.
267      '';
268    };
269
270    WorkingDirectory = mkOption {
271      type = types.nullOr types.str;
272      default = null;
273      description = ''
274        This optional key is used to specify a directory to `chdir(2)` to before running the job.
275      '';
276    };
277
278    EnvironmentVariables = mkOption {
279      type = types.nullOr (types.attrsOf types.str);
280      default = null;
281      description = ''
282        This optional key is used to specify additional environment variables to be set before running the
283        job.
284      '';
285    };
286
287    Umask = mkOption {
288      type = types.nullOr types.int;
289      default = null;
290      description = ''
291        This optional key specifies what value should be passed to `umask(2)` before running the job. Known bug:
292        Property lists don't support octal, so please convert the value to decimal.
293      '';
294    };
295
296    TimeOut = mkOption {
297      type = types.nullOr types.int;
298      default = null;
299      description = ''
300        The recommended idle time out (in seconds) to pass to the job. If no value is specified, a default time
301        out will be supplied by launchd for use by the job at check in time.
302      '';
303    };
304
305    ExitTimeOut = mkOption {
306      type = types.nullOr types.int;
307      default = null;
308      description = ''
309        The amount of time launchd waits before sending a SIGKILL signal. The default value is 20 seconds. The
310        value zero is interpreted as infinity.
311      '';
312    };
313
314    ThrottleInterval = mkOption {
315      type = types.nullOr types.int;
316      default = null;
317      description = ''
318        This key lets one override the default throttling policy imposed on jobs by launchd.  The value is in
319        seconds, and by default, jobs will not be spawned more than once every 10 seconds.  The principle
320        behind this is that jobs should linger around just in case they are needed again in the near future.
321        This not only reduces the latency of responses, but it encourages developers to amortize the cost of
322        program invocation.
323      '';
324    };
325
326    InitGroups = mkOption {
327      type = types.nullOr types.bool;
328      default = null;
329      description = ''
330        This optional key specifies whether `initgroups(3)` should be called before running the job.  The default
331        is true in 10.5 and false in 10.4. This key will be ignored if the UserName key is not set.
332      '';
333    };
334
335    WatchPaths = mkOption {
336      type = types.nullOr (types.listOf types.path);
337      default = null;
338      description = ''
339        This optional key causes the job to be started if any one of the listed paths are modified.
340      '';
341    };
342
343    QueueDirectories = mkOption {
344      type = types.nullOr (types.listOf types.str);
345      default = null;
346      description = ''
347        Much like the WatchPaths option, this key will watch the paths for modifications. The difference being
348        that the job will only be started if the path is a directory and the directory is not empty.
349      '';
350    };
351
352    StartOnMount = mkOption {
353      type = types.nullOr types.bool;
354      default = null;
355      description = ''
356        This optional key causes the job to be started every time a filesystem is mounted.
357      '';
358    };
359
360    StartInterval = mkOption {
361      type = types.nullOr types.int;
362      default = null;
363      description = ''
364        This optional key causes the job to be started every N seconds.  If the system is asleep, the job will
365        be started the next time the computer wakes up.  If multiple intervals transpire before the computer is
366        woken, those events will be coalesced into one event upon wake from sleep.
367      '';
368    };
369
370    StartCalendarInterval = mkOption {
371      default = null;
372      example = {
373        Hour = 2;
374        Minute = 30;
375      };
376      description = ''
377        This optional key causes the job to be started every calendar interval as specified. Missing arguments
378        are considered to be wildcard. The semantics are much like `crontab(5)`.  Unlike cron which skips job
379        invocations when the computer is asleep, launchd will start the job the next time the computer wakes
380        up.  If multiple intervals transpire before the computer is woken, those events will be coalesced into
381        one event upon wake from sleep.
382      '';
383      type = types.nullOr (types.listOf (types.submodule {
384        options = {
385          Minute = mkOption {
386            type = types.nullOr types.int;
387            default = null;
388            description = ''
389              The minute on which this job will be run.
390            '';
391          };
392
393          Hour = mkOption {
394            type = types.nullOr types.int;
395            default = null;
396            description = ''
397              The hour on which this job will be run.
398            '';
399          };
400
401          Day = mkOption {
402            type = types.nullOr types.int;
403            default = null;
404            description = ''
405              The day on which this job will be run.
406            '';
407          };
408
409          Weekday = mkOption {
410            type = types.nullOr types.int;
411            default = null;
412            description = ''
413              The weekday on which this job will be run (0 and 7 are Sunday).
414            '';
415          };
416
417          Month = mkOption {
418            type = types.nullOr types.int;
419            default = null;
420            description = ''
421              The month on which this job will be run.
422            '';
423          };
424        };
425      }));
426    };
427
428    StandardInPath = mkOption {
429      type = types.nullOr types.path;
430      default = null;
431      description = ''
432        This optional key specifies what file should be used for data being supplied to stdin when using
433        `stdio(3)`.
434      '';
435    };
436
437    StandardOutPath = mkOption {
438      type = types.nullOr types.path;
439      default = null;
440      description = ''
441        This optional key specifies what file should be used for data being sent to stdout when using `stdio(3)`.
442      '';
443    };
444
445    StandardErrorPath = mkOption {
446      type = types.nullOr types.path;
447      default = null;
448      description = ''
449        This optional key specifies what file should be used for data being sent to stderr when using `stdio(3)`.
450      '';
451    };
452
453    Debug = mkOption {
454      type = types.nullOr types.bool;
455      default = null;
456      description = ''
457        This optional key specifies that launchd should adjust its log mask temporarily to LOG_DEBUG while
458        dealing with this job.
459      '';
460    };
461
462    WaitForDebugger = mkOption {
463      type = types.nullOr types.bool;
464      default = null;
465      description = ''
466        This optional key specifies that launchd should instruct the kernel to have the job wait for a debugger
467        to attach before any code in the job is executed.
468      '';
469    };
470
471    SoftResourceLimits = mkOption {
472      default = null;
473      description = ''
474        Resource limits to be imposed on the job. These adjust variables set with `setrlimit(2)`.  The following
475        keys apply:
476      '';
477      type = types.nullOr (types.submodule {
478        options = {
479          Core = mkOption {
480            type = types.nullOr types.int;
481            default = null;
482            description = ''
483              The largest size (in bytes) core file that may be created.
484            '';
485          };
486
487          CPU = mkOption {
488            type = types.nullOr types.int;
489            default = null;
490            description = ''
491              The maximum amount of cpu time (in seconds) to be used by each process.
492            '';
493          };
494
495          Data = mkOption {
496            type = types.nullOr types.int;
497            default = null;
498            description = ''
499              The maximum size (in bytes) of the data segment for a process; this defines how far a program may
500              extend its break with the `sbrk(2)` system call.
501            '';
502          };
503
504          FileSize = mkOption {
505            type = types.nullOr types.int;
506            default = null;
507            description = ''
508              The largest size (in bytes) file that may be created.
509            '';
510          };
511
512          MemoryLock = mkOption {
513            type = types.nullOr types.int;
514            default = null;
515            description = ''
516              The maximum size (in bytes) which a process may lock into memory using the mlock(2) function.
517            '';
518          };
519
520          NumberOfFiles = mkOption {
521            type = types.nullOr types.int;
522            default = null;
523            description = ''
524              The maximum number of open files for this process.  Setting this value in a system wide daemon
525              will set the `sysctl(3)` kern.maxfiles (SoftResourceLimits) or kern.maxfilesperproc (HardResourceLimits)
526              value in addition to the `setrlimit(2)` values.
527            '';
528          };
529
530          NumberOfProcesses = mkOption {
531            type = types.nullOr types.int;
532            default = null;
533            description = ''
534              The maximum number of simultaneous processes for this user id.  Setting this value in a system
535              wide daemon will set the `sysctl(3)` kern.maxproc (SoftResourceLimits) or kern.maxprocperuid
536              (HardResourceLimits) value in addition to the `setrlimit(2)` values.
537            '';
538          };
539
540          ResidentSetSize = mkOption {
541            type = types.nullOr types.int;
542            default = null;
543            description = ''
544              The maximum size (in bytes) to which a process's resident set size may grow.  This imposes a
545              limit on the amount of physical memory to be given to a process; if memory is tight, the system
546              will prefer to take memory from processes that are exceeding their declared resident set size.
547            '';
548          };
549
550          Stack = mkOption {
551            type = types.nullOr types.int;
552            default = null;
553            description = ''
554              The maximum size (in bytes) of the stack segment for a process; this defines how far a program's
555              stack segment may be extended.  Stack extension is performed automatically by the system.
556            '';
557          };
558        };
559      });
560    };
561
562    HardResourceLimits = mkOption {
563      default = null;
564      example = { NumberOfFiles = 4096; };
565      description = ''
566        Resource limits to be imposed on the job. These adjust variables set with `setrlimit(2)`.  The following
567        keys apply:
568      '';
569      type = types.nullOr (types.submodule {
570        options = {
571          Core = mkOption {
572            type = types.nullOr types.int;
573            default = null;
574            description = ''
575              The largest size (in bytes) core file that may be created.
576            '';
577          };
578
579          CPU = mkOption {
580            type = types.nullOr types.int;
581            default = null;
582            description = ''
583              The maximum amount of cpu time (in seconds) to be used by each process.
584            '';
585          };
586
587          Data = mkOption {
588            type = types.nullOr types.int;
589            default = null;
590            description = ''
591              The maximum size (in bytes) of the data segment for a process; this defines how far a program may
592              extend its break with the `sbrk(2)` system call.
593            '';
594          };
595
596          FileSize = mkOption {
597            type = types.nullOr types.int;
598            default = null;
599            description = ''
600              The largest size (in bytes) file that may be created.
601            '';
602          };
603
604          MemoryLock = mkOption {
605            type = types.nullOr types.int;
606            default = null;
607            description = ''
608              The maximum size (in bytes) which a process may lock into memory using the `mlock(2)` function.
609            '';
610          };
611
612          NumberOfFiles = mkOption {
613            type = types.nullOr types.int;
614            default = null;
615            description = ''
616              The maximum number of open files for this process.  Setting this value in a system wide daemon
617              will set the `sysctl(3)` kern.maxfiles (SoftResourceLimits) or kern.maxfilesperproc (HardResourceLimits)
618              value in addition to the `setrlimit(2)` values.
619            '';
620          };
621
622          NumberOfProcesses = mkOption {
623            type = types.nullOr types.int;
624            default = null;
625            description = ''
626              The maximum number of simultaneous processes for this user id.  Setting this value in a system
627              wide daemon will set the `sysctl(3)` kern.maxproc (SoftResourceLimits) or kern.maxprocperuid
628              (HardResourceLimits) value in addition to the `setrlimit(2)` values.
629            '';
630          };
631
632          ResidentSetSize = mkOption {
633            type = types.nullOr types.int;
634            default = null;
635            description = ''
636              The maximum size (in bytes) to which a process's resident set size may grow.  This imposes a
637              limit on the amount of physical memory to be given to a process; if memory is tight, the system
638              will prefer to take memory from processes that are exceeding their declared resident set size.
639            '';
640          };
641
642          Stack = mkOption {
643            type = types.nullOr types.int;
644            default = null;
645            description = ''
646              The maximum size (in bytes) of the stack segment for a process; this defines how far a program's
647              stack segment may be extended.  Stack extension is performed automatically by the system.
648            '';
649          };
650        };
651      });
652    };
653
654    Nice = mkOption {
655      type = types.nullOr types.int;
656      default = null;
657      description = ''
658        This optional key specifies what nice(3) value should be applied to the daemon.
659      '';
660    };
661
662    ProcessType = mkOption {
663      type = types.nullOr
664        (types.enum [ "Background" "Standard" "Adaptive" "Interactive" ]);
665      default = null;
666      example = "Background";
667      description = ''
668        This optional key describes, at a high level, the intended purpose of the job.  The system will apply
669        resource limits based on what kind of job it is. If left unspecified, the system will apply light
670        resource limits to the job, throttling its CPU usage and I/O bandwidth. The following are valid values:
671
672           Background
673           : Background jobs are generally processes that do work that was not directly requested by the user.
674             The resource limits applied to Background jobs are intended to prevent them from disrupting the
675             user experience.
676
677           Standard
678           :  Standard jobs are equivalent to no ProcessType being set.
679
680           Adaptive
681           :  Adaptive jobs move between the Background and Interactive classifications based on activity over
682              XPC connections. See {manpage}`xpc_transaction_begin(3)` for details.
683
684           Interactive
685           :  Interactive jobs run with the same resource limitations as apps, that is to say, none. Interactive
686              jobs are critical to maintaining a responsive user experience, and this key should only be
687              used if an app's ability to be responsive depends on it, and cannot be made Adaptive.
688      '';
689    };
690
691    AbandonProcessGroup = mkOption {
692      type = types.nullOr types.bool;
693      default = null;
694      description = ''
695        When a job dies, launchd kills any remaining processes with the same process group ID as the job. Setting
696        this key to true disables that behavior.
697      '';
698    };
699
700    LowPriorityIO = mkOption {
701      type = types.nullOr types.bool;
702      default = null;
703      description = ''
704        This optional key specifies whether the kernel should consider this daemon to be low priority when
705        doing file system I/O.
706      '';
707    };
708
709    LaunchOnlyOnce = mkOption {
710      type = types.nullOr types.bool;
711      default = null;
712      description = ''
713        This optional key specifies whether the job can only be run once and only once.  In other words, if the
714        job cannot be safely respawned without a full machine reboot, then set this key to be true.
715      '';
716    };
717
718    MachServices = mkOption {
719      default = null;
720      example = { ResetAtClose = true; };
721      description = ''
722        This optional key is used to specify Mach services to be registered with the Mach bootstrap sub-system.
723        Each key in this dictionary should be the name of service to be advertised. The value of the key must
724        be a boolean and set to true.  Alternatively, a dictionary can be used instead of a simple true value.
725
726        Finally, for the job itself, the values will be replaced with Mach ports at the time of check-in with
727        launchd.
728      '';
729      type = types.nullOr (types.submodule {
730        options = {
731          ResetAtClose = mkOption {
732            type = types.nullOr types.bool;
733            default = null;
734            description = ''
735              If this boolean is false, the port is recycled, thus leaving clients to remain oblivious to the
736              demand nature of job. If the value is set to true, clients receive port death notifications when
737              the job lets go of the receive right. The port will be recreated atomically with respect to bootstrap_look_up()
738              calls, so that clients can trust that after receiving a port death notification,
739              the new port will have already been recreated. Setting the value to true should be done with
740              care. Not all clients may be able to handle this behavior. The default value is false.
741            '';
742          };
743
744          HideUntilCheckIn = mkOption {
745            type = types.nullOr types.bool;
746            default = null;
747            description = ''
748              Reserve the name in the namespace, but cause bootstrap_look_up() to fail until the job has
749              checked in with launchd.
750            '';
751          };
752        };
753      });
754    };
755
756    LaunchEvents = mkOption {
757      type = types.nullOr (types.attrs);
758      default = null;
759      description = ''
760        Specifies higher-level event types to be used as launch-on-demand event
761        sources.  Each sub-dictionary defines events for a particular event
762        subsystem, such as "com.apple.iokit.matching", which can be used to
763        launch jobs based on the appearance of nodes in the IORegistry. Each
764        dictionary within the sub-dictionary specifies an event descriptor that
765        is specified to each event subsystem. With this key, the job promises to
766        use the xpc_set_event_stream_handler(3) API to consume events. See
767        xpc_events(3) for more details on event sources.
768      '';
769      example = {
770        "com.apple.iokit.matching" = {
771          "com.apple.usb.device" = {
772            IOMatchLaunchStream = true;
773            IOProviderClass = "IOUSBDevice";
774            idProduct = "*";
775            idVendor = "*";
776          };
777        };
778      };
779    };
780
781    Sockets = mkOption {
782      default = null;
783      description = ''
784        This optional key is used to specify launch on demand sockets that can be used to let launchd know when
785        to run the job. The job must check-in to get a copy of the file descriptors using APIs outlined in
786        launch(3).  The keys of the top level Sockets dictionary can be anything. They are meant for the application
787        developer to use to differentiate which descriptors correspond to which application level protocols
788        (e.g. http vs. ftp vs. DNS...).  At check-in time, the value of each Sockets dictionary key will
789        be an array of descriptors. Daemon/Agent writers should consider all descriptors of a given key to be
790        to be effectively equivalent, even though each file descriptor likely represents a different networking
791        protocol which conforms to the criteria specified in the job configuration file.
792
793        The parameters below are used as inputs to call `getaddrinfo(3)`.
794      '';
795      type = types.nullOr (types.attrsOf (types.submodule {
796        options = {
797          SockType = mkOption {
798            type = types.nullOr (types.enum [ "stream" "dgram" "seqpacket" ]);
799            default = null;
800            description = ''
801              This optional key tells launchctl what type of socket to create. The default is "stream" and
802              other valid values for this key are "dgram" and "seqpacket" respectively.
803            '';
804          };
805
806          SockPassive = mkOption {
807            type = types.nullOr types.bool;
808            default = null;
809            description = ''
810              This optional key specifies whether `listen(2)` or `connect(2)` should be called on the created file
811              descriptor. The default is true ("to listen").
812            '';
813          };
814
815          SockNodeName = mkOption {
816            type = types.nullOr types.str;
817            default = null;
818            description = ''
819              This optional key specifies the node to `connect(2)` or `bind(2)` to.
820            '';
821          };
822
823          SockServiceName = mkOption {
824            type = types.nullOr types.str;
825            default = null;
826            description = ''
827              This optional key specifies the service on the node to `connect(2)` or `bind(2)` to.
828            '';
829          };
830
831          SockFamily = mkOption {
832            type = types.nullOr (types.enum [ "IPv4" "IPv6" ]);
833            default = null;
834            description = ''
835              This optional key can be used to specifically request that "IPv4" or "IPv6" socket(s) be created.
836            '';
837          };
838
839          SockProtocol = mkOption {
840            type = types.nullOr (types.enum [ "TCP" ]);
841            default = null;
842            description = ''
843              This optional key specifies the protocol to be passed to `socket(2)`.  The only value understood by
844              this key at the moment is "TCP".
845            '';
846          };
847
848          SockPathName = mkOption {
849            type = types.nullOr types.path;
850            default = null;
851            description = ''
852              This optional key implies SockFamily is set to "Unix". It specifies the path to `connect(2)` or
853              `bind(2)` to.
854            '';
855          };
856
857          SecureSocketWithKey = mkOption {
858            type = types.nullOr types.str;
859            default = null;
860            description = ''
861              This optional key is a variant of SockPathName. Instead of binding to a known path, a securely
862              generated socket is created and the path is assigned to the environment variable that is inherited
863              by all jobs spawned by launchd.
864            '';
865          };
866
867          SockPathMode = mkOption {
868            type = types.nullOr types.int;
869            default = null;
870            description = ''
871              This optional key specifies the mode of the socket. Known bug: Property lists don't support
872              octal, so please convert the value to decimal.
873            '';
874          };
875
876          Bonjour = mkOption {
877            type =
878              types.nullOr (types.either types.bool (types.listOf types.str));
879            default = null;
880            description = ''
881              This optional key can be used to request that the service be registered with the
882              `mDNSResponder(8)`.  If the value is boolean, the service name is inferred from the SockServiceName.
883            '';
884          };
885
886          MulticastGroup = mkOption {
887            type = types.nullOr types.str;
888            default = null;
889            description = ''
890              This optional key can be used to request that the datagram socket join a multicast group.  If the
891              value is a hostname, then `getaddrinfo(3)` will be used to join the correct multicast address for a
892              given socket family.  If an explicit IPv4 or IPv6 address is given, it is required that the SockFamily
893              family also be set, otherwise the results are undefined.
894            '';
895          };
896        };
897      }));
898    };
899  };
900
901  config = { };
902}