Appendix A. Configuration Options

List of email accounts.

Type: attribute set of (submodule)

Default: { }

Declared by:

The email address of this account.

Type: string matching the pattern .*@.*

Example: "jane.doe@example.org"

Declared by:

Whether to enable aerc.

Type: boolean

Default: false

Example: true

Declared by:

Extra config added to the configuration of this account in $HOME/.config/aerc/accounts.conf. See aerc-config(5).

Type: attribute set of (values (null, bool, int, string of float) or a list of values, that will be joined with a comma)

Default: { }

Example: { source = "maildir://~/Maildir/example"; }

Declared by:

Extra bindings specific to this account, added to $HOME/.config/aerc/accounts.conf. See aerc-config(5).

Type: attribute set of attribute set of (values (null, bool, int, string of float) or a list of values, that will be joined with a comma)

Default: { }

Example: { messages = { d = ":move ${folder.trash}<Enter>"; }; }

Declared by:

Extra config specific to this account, added to $HOME/.config/aerc/aerc.conf. See aerc-config(5).

Type: attribute set of attribute set of (values (null, bool, int, string of float) or a list of values, that will be joined with a comma)

Default: { }

Example: { ui = { sidebar-width = 42; }; }

Declared by:

Sets the authentication mechanism if imap is used as the incoming method. See aerc-imap(5).

Type: null or one of "oauthbearer", "xoauth2"

Default: null

Example: "auth"

Declared by:

Sets the oauth2 params if authentication mechanism oauthbearer or xoauth2 is used. See aerc-imap(5).

Type: null or (submodule)

Default: null

Example:

{
  token_endpoint = "<token_endpoint>";
}

Declared by:

Type: null or string

Default: null

Declared by:

Type: null or string

Default: null

Declared by:

Type: null or string

Default: null

Declared by:

Type: null or string

Default: null

Declared by:

Sets the authentication mechanism if smtp is used as the outgoing method. See aerc-smtp(5).

Type: null or one of "none", "plain", "login", "oauthbearer", "xoauth2"

Default: "plain"

Example: "auth"

Declared by:

Sets the oauth2 params if authentication mechanism oauthbearer or xoauth2 is used. See aerc-imap(5).

Type: null or (submodule)

Default: null

Example:

{
  token_endpoint = "<token_endpoint>";
}

Declared by:

Type: null or string

Default: null

Declared by:

Type: null or string

Default: null

Declared by:

Type: null or string

Default: null

Declared by:

Type: null or string

Default: null

Declared by:

Alternative email addresses of this account.

Type: list of string matching the pattern .*@.*

Default: [ ]

Example:

[
  "webmaster@example.org"
  "admin@example.org"
]

Declared by:

Contact completion configuration as expected per alot. See alot's wiki for explanation about possible values.

Type: attribute set of string

Default:

{
  command = "'\${pkgs.notmuch}/bin/notmuch address --format=json --output=recipients  date:6M..'";
  regexp = "'\\[?{\"name\": \"(?P<name>.*)\", \"address\": \"(?P<email>.+)\", \"name-addr\": \".*\"}[,\\]]?'";
  shellcommand_external_filtering = "False";
  type = "shellcommand";
}

Example:

{
  type = "shellcommand";
  command = "abook --mutt-query";
  regexp = "'^(?P<email>[^@]+@[^\t]+)\t+(?P<name>[^\t]+)'";
  ignorecase = "True";
}

Declared by:

Extra settings to add to this Alot account configuration.

Type: strings concatenated with "\n"

Default: ""

Declared by:

Command to send a mail. If msmtp is enabled for the account, then this is set to msmtpq --read-envelope-from --read-recipients.

Type: null or string

Declared by:

Whether to enable Astroid.

Type: boolean

Default: false

Example: true

Declared by:

Extra settings to add to this astroid account configuration.

Type: attribute set of anything

Default: { }

Example:

{
  select_query = "";
}

Declared by:

Command to send a mail. If msmtp is enabled for the account, then this is set to msmtpq --read-envelope-from --read-recipients.

Type: string

Declared by:

Some email providers have peculiar behavior that require special treatment. This option is therefore intended to indicate the nature of the provider.

When this indicates a specific provider then, for example, the IMAP, SMTP, and JMAP server configuration may be set automatically.

Type: one of "plain", "gmail.com", "runbox.com", "fastmail.com", "yandex.com", "outlook.office365.com"

Default: "plain"

Declared by:

Standard email folders.

Type: submodule

Default: { }

Declared by:

Relative path of the drafts mail folder.

Type: null or string

Default: "Drafts"

Declared by:

Relative path of the inbox mail.

Type: string

Default: "Inbox"

Declared by:

Relative path of the sent mail folder.

Type: null or string

Default: "Sent"

Declared by:

Relative path of the deleted mail folder.

Type: string

Default: "Trash"

Declared by:

Whether to enable the getmail mail retriever for this account.

Type: boolean

Default: false

Example: true

Declared by:

Enable if you want to delete read messages from the server. Most users should either enable delete or disable readAll.

Type: boolean

Default: false

Declared by:

Specify a command delivering the incoming mail to your maildir.

Type: null or string

Default: null

Example: "\${pkgs.maildrop}/bin/maildrop"

Declared by:

A non-empty list of mailboxes. To download all mail you can use the ALL mailbox.

Type: non-empty (list of string)

Default: [ ]

Example:

[
  "INBOX"
  "INBOX.spam"
]

Declared by:

Enable if you want to fetch all, even the read messages from the server. Most users should either enable delete or disable readAll.

Type: boolean

Default: true

Declared by:

GPG configuration.

Type: null or (submodule)

Default: null

Declared by:

Encrypt outgoing messages by default.

Type: boolean

Default: false

Declared by:

The key to use as listed in gpg --list-keys.

Type: string

Declared by:

Sign messages by default.

Type: boolean

Default: false

Declared by:

Whether to enable the himalaya mail client for this account .

Type: boolean

Default: false

Example: true

Declared by:

The method for which himalaya will fetch, store, etc. mail.

Type: null or one of "imap", "maildir"

Declared by:

The method for which himalaya will send mail.

Type: null or one of "smtp", "sendmail"

Declared by:

Extra settings to add to this himalaya account configuration.

Type: TOML value

Default: { }

Example:

{
  default-page-size = 50;
}

Declared by:

The IMAP configuration to use for this account.

Type: null or (submodule)

Default: null

Declared by:

Hostname of IMAP server.

Type: string

Example: "imap.example.org"

Declared by:

The port on which the IMAP server listens. If null then the default port is used.

Type: null or 16 bit unsigned integer; between 0 and 65535 (both inclusive)

Default: null

Example: 993

Declared by:

Configuration for secure connections.

Type: submodule

Default: { }

Declared by:

Whether to enable TLS/SSL.

Type: boolean

Default: true

Declared by:

Path to file containing certificate authorities that should be used to validate the connection authenticity. If null then the system default is used. Note, if set then the system default may still be accepted.

Type: null or path

Default: "config.accounts.email.certificatesFile"

Declared by:

Whether to use STARTTLS.

Type: boolean

Default: false

Declared by:

Whether to enable imapnotify.

Type: boolean

Default: false

Example: true

Declared by:

IMAP folders to watch.

Type: list of string

Default: [ ]

Example:

[
  "Inbox"
  "[Gmail]/MyLabel"
]

Declared by:

Additional configuration to add for this account.

Type: attribute set of (boolean or signed integer or string)

Default: { }

Example:

{
  wait = 10;
}

Declared by:

Shell commands to run on any event.

Type: string or attribute set of string

Default: ""

Example: "\${pkgs.isync}/bin/mbsync test-%s"

Declared by:

Shell commands to run after onNotify event.

Type: string or attribute set of string

Default: ""

Example:

{
  mail = "\${pkgs.notmuch}/bin/notmuch new && \${pkgs.libnotify}/bin/notify-send 'New mail arrived'";
}

Declared by:

The JMAP configuration to use for this account.

Type: null or (submodule)

Default: null

Declared by:

Hostname of JMAP server.

If both this option and accounts.email.accounts.<name>.jmap.sessionUrl are specified, host is preferred by applications when establishing a session.

Type: null or string

Default: null

Example: "jmap.example.org"

Declared by:

URL for the JMAP Session resource.

If both this option and accounts.email.accounts.<name>.jmap.host are specified, host is preferred by applications when establishing a session.

Type: null or string

Default: null

Example: "https://jmap.example.org:443/.well-known/jmap"

Declared by:

Whether to enable lieer Gmail synchronization for notmuch.

Type: boolean

Default: false

Example: true

Declared by:

Warn if Notmuch is not also enabled for this account.

This can safely be disabled if notmuch init has been used to configure this account outside of Home Manager.

Type: boolean

Default: true

Declared by:

Settings which are applied to .gmailieer.json for the account.

See the lieer manual for documentation of settings not explicitly covered by this module.

Type: JSON value

Default: { }

Declared by:

Allow missing labels on the Gmail side to be dropped.

Type: boolean

Default: false

Declared by:

Extension to include in local file names, which can be useful for indexing with third-party programs.

Type: string

Default: ""

Example: "mbox"

Declared by:

Work around a Gmail API quirk where an empty change history is sometimes returned.

See this GitHub issue for more details.

Type: boolean

Default: false

Declared by:

Set Gmail labels to ignore when syncing from remote labels to local tags (before translations).

Type: list of string

Default:

[
  "CATEGORY_FORUMS"
  "CATEGORY_PROMOTIONS"
  "CATEGORY_UPDATES"
  "CATEGORY_SOCIAL"
  "CATEGORY_PERSONAL"
]

Declared by:

Set labels to ignore when syncing from local tags to remote labels (after translations).

Type: list of string

Default: [ ]

Declared by:

Local tag to which the remote Gmail 'TRASH' label is translated.

Type: string

Default: "trash"

Declared by:

Remove local messages that have been deleted on the remote.

Type: boolean

Default: true

Declared by:

Replace '/' with '.' in Gmail labels.

Type: boolean

Default: false

Declared by:

HTTP timeout in seconds. 0 means forever or system timeout.

Type: unsigned integer, meaning >=0

Default: 600

Declared by:

Whether to enable lieer synchronization service.

Type: boolean

Default: false

Example: true

Declared by:

How often to synchronize the account.

This value is passed to the systemd timer configuration as the onCalendar option. See systemd.time(7) for more information about the format.

Type: string

Default: "*:0/5"

Declared by:

Maildir configuration for this account.

Type: null or (submodule)

Declared by:

Path to maildir directory where mail for this account is stored. This is relative to the base maildir path.

Type: string

Declared by:

Whether to enable synchronization using mbsync.

Type: boolean

Default: false

Example: true

Declared by:

Automatically create missing mailboxes within the given mail store.

Type: one of "none", "maildir", "imap", "both"

Default: "none"

Example: "maildir"

Declared by:

Permanently remove messages marked for deletion from the given mail store.

Type: one of "none", "maildir", "imap", "both"

Default: "none"

Example: "both"

Declared by:

Account section extra configuration.

Type: attribute set of (string or signed integer or boolean or list of string)

Default: { }

Example:

{
  PipelineDepth = 10;
  Timeout = 60;
};

Declared by:

Per channel extra configuration.

Type: attribute set of (string or signed integer or boolean or list of string)

Default: { }

Example:

{
  MaxMessages = 10000;
  MaxSize = "1m";
};

Declared by:

Local store extra configuration.

Type: attribute set of (string or signed integer or boolean or list of string)

Default: { }

Declared by:

Remote store extra configuration.

Type: attribute set of (string or signed integer or boolean or list of string)

Default: { }

Declared by:

If set, flattens the hierarchy within the maildir by substituting the canonical hierarchy delimiter / with this value.

Type: null or string

Default: null

Example: "."

Declared by:

Some email providers (Gmail) have a different directory hierarchy for synchronized email messages. Namely, when using mbsync without specifying a set of channels into a group, all synchronized directories end up beneath the [Gmail]/ directory.

This option allows you to specify a group, and subsequently channels that will allow you to sync your mail into an arbitrary hierarchy.

Type: attribute set of (submodule)

Default: { }

Declared by:

List of channels that should be grouped together into this group. When performing a synchronization, the groups are synchronized, rather than the individual channels.

Using these channels and then grouping them together allows for you to define the maildir hierarchy as you see fit.

Type: attribute set of (submodule)

Default: { }

Declared by:

Extra configuration lines to add to THIS channel's configuration.

Type: attribute set of (string or signed integer or boolean or list of string)

Default: { }

Example:

{
  Create = "both";
  CopyArrivalDate = "yes";
  MaxMessages = 10000;
  MaxSize = "1m";
}

Declared by:

IMAP4 patterns for which mailboxes on the remote mail server to sync. If Patterns are specified, farPattern is interpreted as a prefix which is not matched against the patterns, and is not affected by mailbox list overrides.

If this is left as the default, then mbsync will default to the pattern INBOX.

Type: string

Default: ""

Example: "[Gmail]/Sent Mail"

Declared by:

The unique name for THIS channel in THIS group. The group will refer to this channel by this name.

In addition, you can manually sync just this channel by specifying this name to mbsync on the command line.

Type: string (read only)

Default: "‹name›"

Declared by:

Name for where mail coming from the remote (far) mail server will end up locally. The mailbox specified by the far pattern will be placed in this directory.

If this is left as the default, then mbsync will default to the pattern INBOX.

Type: string

Default: ""

Example: "Sent"

Declared by:

Instead of synchronizing just the mailboxes that match the farPattern, use it as a prefix which is not matched against the patterns, and is not affected by mailbox list overrides.

Type: list of string

Default: [ ]

Example:

[
  "INBOX"
]

Declared by:

The name of this group for this account. These names are different than some others, because they will hide channel names that are the same.

Type: string (read only)

Default: "‹name›"

Declared by:

Pattern of mailboxes to synchronize.

Type: list of string

Default:

[
  "*"
]

Declared by:

Propagate mailbox deletions to the given mail store.

Type: one of "none", "maildir", "imap", "both"

Default: "none"

Example: "imap"

Declared by:

The on-disk folder naming style. This option has no effect when flatten is used.

Type: one of "Verbatim", "Maildir++", "Legacy"

Default: "Verbatim"

Example: "Maildir++"

Declared by:

Whether to enable msmtp.

If enabled then it is possible to use the --account command line option to send a message for a given account using the msmtp or msmtpq tool. For example, msmtp --account=private would send using the account defined in accounts.email.accounts.private. If the --account option is not given then the primary account will be used.

Type: boolean

Default: false

Declared by:

Extra configuration options to add to ~/.msmtprc. See https://marlam.de/msmtp/msmtprc.txt for examples.

Type: attribute set of string

Default: { }

Example:

{
  auth = "login";
}

Declared by:

Fingerprint of a trusted TLS certificate. The fingerprint can be obtained by executing msmtp --serverinfo --tls --tls-certcheck=off.

Type: null or string matching the pattern ([[:alnum:]]{2}:)+[[:alnum:]]{2}

Default: null

Example: "my:SH:a2:56:ha:sh"

Declared by:

Whether to enable mu indexing.

Type: boolean

Default: false

Example: true

Declared by:

Whether to enable mujmap JMAP synchronization for notmuch.

Type: boolean

Default: false

Example: true

Declared by:

Warn if Notmuch is not also enabled for this account.

This can safely be disabled if mujmap.toml is managed outside of Home Manager.

Type: boolean

Default: true

Declared by:

Settings which are applied to mujmap.toml for the account.

See the mujmap project for documentation of settings not explicitly covered by this module.

Type: TOML value

Default: { }

Declared by:

Whether to create new mailboxes automatically on the server from notmuch tags.

Type: boolean

Default: true

Declared by:

The cache directory in which to store mail files while they are being downloaded. The default is operating-system specific.

Type: null or string

Default: null

Declared by:

Fully qualified domain name of the JMAP service.

mujmap looks up the JMAP SRV record for this host to determine the JMAP session URL. Mutually exclusive with accounts.email.accounts.<name>.mujmap.settings.session_url.

If null, defaults to accounts.email.accounts.<name>.jmap.host.

Type: null or string

Default: null

Example: "example.com"

Declared by:

Shell command which will print a password to stdout for basic HTTP authentication.

If null, defaults to accounts.email.accounts.<name>.passwordCommand.

Type: null or string or list of string

Default: null

Example: "pass alice@example.com"

Declared by:

Session URL to connect to.

Mutually exclusive with accounts.email.accounts.<name>.mujmap.settings.fqdn.

If null, defaults to accounts.email.accounts.<name>.jmap.sessionUrl.

Type: null or string

Default: null

Example: "https://jmap.example.com/.well-known/jmap"

Declared by:

Tag configuration.

Beware that there are quirks that require manual consideration if changing the values of these files; please see https://github.com/elizagamedev/mujmap/blob/main/mujmap.toml.example for more details.

Type: TOML value

Default: { }

Declared by:

Tag for notmuch to use for messages stored in the mailbox labeled with the Trash name attribute.

If set to an empty string, this mailbox and its child mailboxes are not synchronized with a tag.

Type: string

Default: "deleted"

Declared by:

Directory separator for mapping notmuch tags to maildirs.

Type: string

Default: "/"

Example: "."

Declared by:

Tag for notmuch to use for messages stored in the mailbox labeled with the Important name attribute and/or with the $Important keyword.

If set to an empty string, this mailbox, its child mailboxes, and these keywords are not synchronized with a tag.

Type: string

Default: "important"

Declared by:

Tag for notmuch to use for messages stored in the mailbox labeled with the Inbox name attribute.

If set to an empty string, this mailbox and its child mailboxes are not synchronized with a tag.

Type: string

Default: "inbox"

Declared by:

If true, translate all mailboxes to lowercase names when mapping to notmuch tags.

Type: boolean

Default: false

Declared by:

Tag for notmuch to use for the IANA $Phishing keyword.

If set to an empty string, this keyword is not synchronized with a tag.

Type: string

Default: "phishing"

Declared by:

Tag for notmuch to use for messages stored in the mailbox labeled with the Sent name attribute.

If set to an empty string, this mailbox and its child mailboxes are not synchronized with a tag.

Type: string

Default: "sent"

Declared by:

Tag for notmuch to use for messages stored in the mailbox labeled with the Junk name attribute and/or with the $Junk keyword, except for messages with the $NotJunk keyword.

If set to an empty string, this mailbox, its child mailboxes, and these keywords are not synchronized with a tag.

Type: string

Default: "spam"

Declared by:

Username for basic HTTP authentication.

If null, defaults to accounts.email.accounts.<name>.userName.

Type: null or string

Default: null

Example: "alice@example.com"

Declared by:

Unique identifier of the account. This is set to the attribute name of the account configuration.

Type: string (read only)

Declared by:

Whether to enable NeoMutt.

Type: boolean

Default: false

Example: true

Declared by:

Extra lines to add to the folder hook for this account.

Type: strings concatenated with "\n"

Default: ""

Example: "color status cyan default"

Declared by:

List of extra mailboxes

Type: list of (string or (submodule))

Default: [ ]

Declared by:

Use a different name as mailbox name

Type: null or string

Default: null

Example: "==== <mailbox-name> ==="

Declared by:

Command to send a mail. If not set, neomutt will be in charge of sending mails.

Type: null or string

Default:

if config.msmtp.enable then
  "msmtpq --read-envelope-from --read-recipients"
else
  null

Example: "msmtpq --read-envelope-from --read-recipients"

Declared by:

Whether to enable notmuch indexing.

Type: boolean

Default: false

Example: true

Declared by:

Whether to enable Notmuch support in NeoMutt.

Type: boolean

Default: true

Example: true

Declared by:

List of virtual mailboxes using Notmuch queries

Type: list of (submodule)

Default:

[
  {
    name = "My INBOX";
    query = "tag:inbox";
  }
]

Example:

[
  {
    name = "My INBOX";
    query = "tag:inbox";
  }
]

Declared by:

Restricts number of messages/threads in the result.

Type: null or signed integer

Default: null

Example: 10

Declared by:

Name to display

Type: string

Default: "My INBOX"

Example: "My INBOX"

Declared by:

Notmuch query

Type: string

Default: "tag:inbox"

Example: "tag:inbox"

Declared by:

Reads all matching messages or whole-threads. The default is 'messages' or nm_query_type.

Type: null or one of "threads", "messages"

Default: null

Example: "threads"

Declared by:

Whether to enable OfflineIMAP.

Type: boolean

Default: false

Example: true

Declared by:

Extra configuration options to add to the account section.

Type: attribute set of (string or signed integer or boolean)

Default: { }

Example:

{
  autorefresh = 20;
}

Declared by:

Extra configuration options to add to the local account section.

Type: attribute set of (string or signed integer or boolean)

Default: { }

Example:

{
  sync_deletes = true;
}

Declared by:

Extra configuration options to add to the remote account section.

Type: attribute set of (string or signed integer or boolean)

Default: { }

Example:

{
  expunge = false;
  maxconnections = 2;
}

Declared by:

Command to run after fetching new mails.

Type: strings concatenated with "\n"

Default: ""

Declared by:

A command, which when run writes the account password on standard output.

Type: null or string or list of string

Default: null

Example: "secret-tool lookup email me@example.org"

Declared by:

Whether this is the primary account. Only one account may be set as primary.

Type: boolean

Default: false

Declared by:

Name displayed when sending mails.

Type: string

Example: "Jane Doe"

Declared by:

Signature configuration.

Type: submodule

Default: { }

Declared by:

A command that generates a signature.

Type: null or path

Default: null

Example:

pkgs.writeScript "signature" "echo This is my signature"

Declared by:

The delimiter used between the document and the signature.

Type: string

Default:

''
  --
''

Example:

~*~*~*~*~*~*~*~*~*~*~*~

Declared by:

Method to communicate the signature.

Type: one of "append", "attach", "none"

Default: "none"

Declared by:

Signature content.

Type: string

Default: ""

Example:

''
  --
  Luke Skywalker
  May the force be with you.
''

Declared by:

The SMTP configuration to use for this account.

Type: null or (submodule)

Default: null

Declared by:

Hostname of SMTP server.

Type: string

Example: "smtp.example.org"

Declared by:

The port on which the SMTP server listens. If null then the default port is used.

Type: null or 16 bit unsigned integer; between 0 and 65535 (both inclusive)

Default: null

Example: 465

Declared by:

Configuration for secure connections.

Type: submodule

Default: { }

Declared by:

Whether to enable TLS/SSL.

Type: boolean

Default: true

Declared by:

Path to file containing certificate authorities that should be used to validate the connection authenticity. If null then the system default is used. Note, if set then the system default may still be accepted.

Type: null or path

Default: "config.accounts.email.certificatesFile"

Declared by:

Whether to use STARTTLS.

Type: boolean

Default: false

Declared by:

Whether to enable the Thunderbird mail client for this account.

Type: boolean

Default: false

Example: true

Declared by:

List of Thunderbird profiles for which this account should be enabled. If this list is empty (the default), this account will be enabled for all declared profiles.

Type: list of string

Default: [ ]

Example:

[ "profile1" "profile2" ]

Declared by:

Extra settings to add to this Thunderbird account configuration. The id given as argument is an automatically generated account identifier.

Type: function that evaluates to a(n) attribute set of (boolean or signed integer or string)

Default: _: { }

Example:

id: {
  "mail.identity.id_${id}.protectSubject" = false;
  "mail.identity.id_${id}.autoEncryptDrafts" = false;
};

Declared by:

The server username of this account. This will be used as the SMTP, IMAP, and JMAP user name.

Type: null or string

Default: null

Declared by:

Path to default file containing certificate authorities that should be used to validate the connection authenticity. This path may be overridden on a per-account basis.

Type: null or path

Default: "/etc/ssl/certs/ca-certificates.crt"

Declared by:

The base directory for account maildir directories. May be a relative path, in which case it is relative the home directory.

Type: string

Default: "$HOME/Maildir"

Declared by:

Settings to write to the dconf configuration system.

Type: attribute set of attribute set of (GVariant value)

Default: { }

Example:

{
  "org/gnome/calculator" = {
    button-mode = "programming";
    show-thousands = true;
    base = 10;
    word-size = 64;
    window-position = lib.hm.gvariant.mkTuple [100 100];
  };
}

Declared by:

Whether to enable EditorConfig home configuration file.

Type: boolean

Default: false

Example: true

Declared by:

Configuration written to $HOME/.editorconfig. root = true is automatically added to the file, it must not be added here. See https://editorconfig.org for documentation.

Type: attribute set of attribute set of (INI atom (null, bool, int, float or string))

Default: { }

Example:

{
  "*" = {
    charset = "utf-8";
    end_of_line = "lf";
    trim_trailing_whitespace = true;
    insert_final_newline = true;
    max_line_width = 78;
    indent_style = "space";
    indent_size = 4;
  };
};

Declared by:

Whether to enable fontconfig configuration. This will, for example, allow fontconfig to discover fonts and configurations installed through home.packages and nix-env.

Type: boolean

Default: false

Declared by:

Whether to enable GTK 2/3 configuration.

Type: boolean

Default: false

Example: true

Declared by:

The cursor theme to use.

Type: null or (submodule)

Default: null

Declared by:

Package providing the cursor theme. This package will be installed to your profile. If null then the theme is assumed to already be available in your profile.

Type: null or package

Default: null

Example: pkgs.vanilla-dmz

Declared by:

The name of the cursor theme within the package.

Type: string

Example: "Vanilla-DMZ"

Declared by:

The size of the cursor.

Type: null or signed integer

Default: null

Example: 16

Declared by:

The font to use in GTK+ 2/3 applications.

Type: null or (submodule)

Default: null

Declared by:

Package providing the font. This package will be installed to your profile. If null then the font is assumed to already be available in your profile.

Type: null or package

Default: null

Example: pkgs.dejavu_fonts

Declared by:

The family name of the font within the package.

Type: string

Example: "DejaVu Sans"

Declared by:

The size of the font.

Type: null or signed integer or floating point number

Default: null

Example: "8"

Declared by:

The location to put the GTK configuration file.

Type: path

Default: "${config.home.homeDirectory}/.gtkrc-2.0"

Example: "${config.xdg.configHome}/gtk-2.0/gtkrc"

Declared by:

Extra configuration lines to add verbatim to ~/.gtkrc-2.0.

Type: strings concatenated with "\n"

Default: ""

Example: "gtk-can-change-accels = 1"

Declared by:

Bookmarks in the sidebar of the GTK file browser

Type: list of string

Default: [ ]

Example:

[
  "file:///home/jane/Documents"
]

Declared by:

Extra configuration options to add to $XDG_CONFIG_HOME/gtk-3.0/settings.ini.

Type: attribute set of (boolean or signed integer or string)

Default: { }

Example:

{
  gtk-cursor-blink = false;
  gtk-recent-files-limit = 20;
}

Declared by:

Extra configuration lines to add verbatim to $XDG_CONFIG_HOME/gtk-3.0/gtk.css.

Type: strings concatenated with "\n"

Default: ""

Declared by:

Extra configuration options to add to $XDG_CONFIG_HOME/gtk-4.0/settings.ini.

Type: attribute set of (boolean or signed integer or string)

Default: { }

Example:

{
  gtk-cursor-blink = false;
  gtk-recent-files-limit = 20;
}

Declared by:

The icon theme to use.

Type: null or (submodule)

Default: null

Declared by:

Package providing the icon theme. This package will be installed to your profile. If null then the theme is assumed to already be available in your profile.

Type: null or package

Default: null

Example: pkgs.gnome.adwaita-icon-theme

Declared by:

The name of the icon theme within the package.

Type: string

Example: "Adwaita"

Declared by:

The GTK+2/3 theme to use.

Type: null or (submodule)

Default: null

Declared by:

Package providing the theme. This package will be installed to your profile. If null then the theme is assumed to already be available in your profile.

Type: null or package

Default: null

Example: pkgs.gnome.gnome-themes-extra

Declared by:

The name of the theme within the package.

Type: string

Example: "Adwaita"

Declared by:

Some Nix-packages provide debug symbols for gdb in the debug-output. This option ensures that those are automatically fetched from the binary cache if available and gdb is configured to find those symbols.

Type: boolean

Default: false

Example: true

Declared by:

Determines whether to check for release version mismatch between Home Manager and Nixpkgs. Using mismatched versions is likely to cause errors and unexpected behavior. It is therefore highly recommended to use a release of Home Manager than corresponds with your chosen release of Nixpkgs.

When this option is enabled and a mismatch is detected then a warning will be printed when the user configuration is being built.

Type: boolean

Default: false

Declared by:

The set of packages to appear in the user environment.

Type: list of package

Default: [ ]

Declared by:

The activation scripts blocks to run when activating a Home Manager generation. Any entry here should be idempotent, meaning running twice or more times produces the same result as running it once.

If the script block produces any observable side effect, such as writing or deleting files, then it must be placed after the special writeBoundary script block. Prior to the write boundary one can place script blocks that verifies, but does not modify, the state of the system and exits if an unexpected state is found. For example, the checkLinkTargets script block checks for collisions between non-managed files and files defined in home.file.

A script block should respect the DRY_RUN variable, if it is set then the actions taken by the script should be logged to standard out and not actually performed. The variable DRY_RUN_CMD is set to echo if dry run is enabled.

A script block should also respect the VERBOSE variable, and if set print information on standard out that may be useful for debugging any issue that may arise. The variable VERBOSE_ARG is set to --verbose if verbose output is enabled.

Type: DAG of string

Default: { }

Example:

{
  myActivationAction = lib.hm.dag.entryAfter ["writeBoundary"] ''
    $DRY_RUN_CMD ln -s $VERBOSE_ARG \
        ${builtins.toPath ./link-me-directly} $HOME
  '';
}

Declared by:

List of additional package outputs of the packages home.packages that should be installed into the user environment.

Type: list of string

Default: [ ]

Example:

[
  "doc"
  "info"
  "devdoc"
]

Declared by:

Attribute set of files to link into the user home.

Type: attribute set of (submodule)

Default: { }

Declared by:

Whether this file should be generated. This option allows specific files to be disabled.

Type: boolean

Default: true

Declared by:

Set the execute bit. If null, defaults to the mode of the source file or to false for files created through the text option.

Type: null or boolean

Default: null

Declared by:

Shell commands to run when file has changed between generations. The script will be run after the new files have been linked into place.

Note, this code is always run when recursive is enabled.

Type: strings concatenated with "\n"

Default: ""

Declared by:

If the file source is a directory, then this option determines whether the directory should be recursively linked to the target location. This option has no effect if the source is a file.

If false (the default) then the target will be a symbolic link to the source directory. If true then the target will be a directory structure matching the source's but whose leafs are symbolic links to the files of the source directory.

Type: boolean

Default: false

Declared by:

Path of the source file or directory. If home.file.<name>.text is non-null then this option will automatically point to a file containing that text.

Type: path

Declared by:

Path to target file relative to HOME.

Type: string

Declared by:

Text of the file. If this option is null then home.file.<name>.source must be set.

Type: null or strings concatenated with "\n"

Default: null

Declared by:

The user's home directory. Must be an absolute path.

Type: path

Example: "/home/jane.doe"

Declared by:

Keyboard configuration. Set to null to disable Home Manager keyboard management.

Type: null or (submodule)

Default:

"{ }"  for state version < 21.11,
"null" for state version ≥ 21.11

Declared by:

Keyboard layout. If null, then the system configuration will be used.

This defaults to null for state version ≥ 19.09 and "us" otherwise.

Type: null or string

Default: null

Declared by:

Keyboard model.

Type: null or string

Default: null

Example: "presario"

Declared by:

X keyboard options; layout switching goes here.

Type: list of string

Default: [ ]

Example:

[
  "grp:caps_toggle"
  "grp_led:scroll"
]

Declared by:

X keyboard variant. If null, then the system configuration will be used.

This defaults to null for state version ≥ 19.09 and "" otherwise.

Type: null or string

Default: null

Example: "colemak"

Declared by:

Language configuration.

Type: submodule

Default: { }

Declared by:

The language to use for addresses.

Type: null or string

Default: null

Declared by:

The language to use unless overridden by a more specific option.

Type: null or string

Default: null

Declared by:

The language to use for collation (alphabetical ordering).

Type: null or string

Default: null

Declared by:

Character classification category.

Type: null or string

Default: null

Declared by:

The language to use for measurement values.

Type: null or string

Default: null

Declared by:

The language to use for messages, application UI languages, etc.

Type: null or string

Default: null

Declared by:

The language to use for formatting currencies and money amounts.

Type: null or string

Default: null

Declared by:

The language to use for personal names.

Type: null or string

Default: null

Declared by:

The language to use for numerical values.

Type: null or string

Default: null

Declared by:

The language to use for paper sizes.

Type: null or string

Default: null

Declared by:

The language to use for telephone numbers.

Type: null or string

Default: null

Declared by:

The language to use for formatting times.

Type: null or string

Default: null

Declared by:

Cursor configuration. Set to null to disable.

Top-level options declared under this submodule are backend independent options. Options declared under namespaces such as x11 are backend specific options. By default, only backend independent cursor configurations are generated. If you need configurations for specific backends, you can toggle them via the enable option. For example, home.pointerCursor.x11.enable will enable x11 cursor configurations.

Type: null or (submodule)

Default: null

Declared by:

Package providing the cursor theme.

Type: package

Example: pkgs.vanilla-dmz

Declared by:

Whether to enable gtk config generation for home.pointerCursor .

Type: boolean

Default: false

Example: true

Declared by:

The cursor name within the package.

Type: string

Example: "Vanilla-DMZ"

Declared by:

The cursor size.

Type: signed integer

Default: 32

Example: 64

Declared by:

Whether to enable x11 config generation for home.pointerCursor .

Type: boolean

Default: false

Example: true

Declared by:

The default cursor file to use within the package.

Type: string

Default: "left_ptr"

Example: "X_cursor"

Declared by:

The profile directory where Home Manager generations are installed.

Type: path (read only)

Declared by:

Extra directories to add to PATH.

These directories are added to the PATH variable in a double-quoted context, so expressions like $HOME are expanded by the shell. However, since expressions like ~ or * are escaped, they will end up in the PATH verbatim.

Type: list of string

Default: [ ]

Example:

[
  "$HOME/.local/bin"
  "\${xdg.configHome}/emacs/bin"
  ".git/safe/../../bin"
]

Declared by:

Environment variables to always set at login.

The values may refer to other environment variables using POSIX.2 style variable references. For example, a variable parameter may be referenced as $parameter or ${parameter}. A default value foo may be given as per ${parameter:-foo} and, similarly, an alternate value bar can be given as per ${parameter:+bar}.

Note, these variables may be set in any order so no session variable may have a runtime dependency on another session variable. In particular code like

home.sessionVariables = {
  FOO = "Hello";
  BAR = "$FOO World!";
};

may not work as expected. If you need to reference another session variable, then do so inside Nix instead. The above example then becomes

home.sessionVariables = {
  FOO = "Hello";
  BAR = "${config.home.sessionVariables.FOO} World!";
};

Type: lazy attribute set of (string or path or signed integer or floating point number)

Default: { }

Example:

{
  EDITOR = "emacs";
  GS_OPTIONS = "-sPAPERSIZE=a4";
}

Declared by:

An attribute set that maps aliases (the top level attribute names in this option) to command strings or directly to build outputs.

This option should only be used to manage simple aliases that are compatible across all shells. If you need to use a shell specific feature then make sure to use a shell specific option, for example programs.bash.shellAliases for Bash.

Type: attribute set of string

Default: { }

Example:

{
  g = "git";
  "..." = "cd ../..";
}

Declared by:

It is occasionally necessary for Home Manager to change configuration defaults in a way that is incompatible with stateful data. This could, for example, include switching the default data format or location of a file.

The state version indicates which default settings are in effect and will therefore help avoid breaking program configurations. Switching to a higher state version typically requires performing some manual steps, such as data conversion or moving files.

Type: one of "18.09", "19.03", "19.09", "20.03", "20.09", "21.03", "21.05", "21.11", "22.05", "22.11", "23.05"

Declared by:

The user's username.

Type: string

Example: "jane.doe"

Declared by:

Select the enabled input method. Input methods is a software to input symbols that are not available on standard input devices.

Input methods are specially used to input Chinese, Japanese and Korean characters.

Currently the following input methods are available in Home Manager:

Type: null or one of "fcitx", "fcitx5", "nabi", "uim", "hime", "kime"

Default: null

Example: "fcitx5"

Declared by:

Enabled Fcitx5 addons.

Type: list of package

Default: [ ]

Example: with pkgs; [ fcitx5-rime ]

Declared by:

kime configuration. Refer to https://github.com/Riey/kime/blob/develop/docs/CONFIGURATION.md for details on supported values.

Type: YAML value

Default: { }

Example:

{
  daemon = {
    modules = ["Xim" "Indicator"];
  };

  indicator = {
    icon_color = "White";
  };

  engine = {
    hangul = {
      layout = "dubeolsik";
    };
  };
}

Declared by:

Selected UIM toolbar.

Type: one of "gtk", "gtk3", "gtk-systray", "gtk3-systray", "qt4"

Default: "gtk"

Example: "gtk-systray"

Declared by:

Whether to enable Home Manager to define per-user daemons by making use of launchd's LaunchAgents.

Type: boolean

Default: pkgs.stdenv.hostPlatform.isDarwin

Declared by:

Define LaunchAgents.

Type: attribute set of (submodule)

Default: { }

Declared by:

Whether to enable ‹name›.

Type: boolean

Default: false

Example: true

Declared by:

Define a launchd job. See launchd.plist(5) for details.

Type: attribute set of anything

Default: { }

Example:

{
  ProgramArguments = [ "/usr/bin/say" "Good afternoon" ];
  StartCalendarInterval = [
    {
      Hour = 12;
      Minute = 0;
    }
  ];
}

Declared by:

When a job dies, launchd kills any remaining processes with the same process group ID as the job. Setting this key to true disables that behavior.

Type: null or boolean

Default: null

Declared by:

This optional key specifies that launchd should adjust its log mask temporarily to LOG_DEBUG while dealing with this job.

Type: null or boolean

Default: null

Declared by:

This optional key is used as a hint to launchctl(1) that it should not submit this job to launchd when loading a job or jobs. The value of this key does NOT reflect the current state of the job on the running system. If you wish to know whether a job is loaded in launchd, reading this key from a configuration file yourself is not a sufficient test. You should query launchd for the presence of the job using the launchctl(1) list subcommand or use the ServiceManagement framework's SMJobCopyDictionary() method. Note that as of Mac OS X v10.6, this key's value in a configuration file conveys a default value, which is changed with the [-w] option of the launchctl(1) load and unload subcommands. These subcommands no longer modify the configuration file, so the value displayed in the configuration file is not necessarily the value that launchctl(1) will apply. See launchctl(1) for more information. Please also be mindful that you should only use this key if the provided on-demand and KeepAlive criteria are insufficient to describe the conditions under which your job needs to run. The cost to have a job loaded in launchd is negligible, so there is no harm in loading a job which only runs once or very rarely.

Type: null or boolean

Default: null

Declared by:

This flag causes launchd to use the glob(3) mechanism to update the program arguments before invocation.

Type: null or boolean

Default: null

Declared by:

This flag instructs launchd that the job promises to use vproc_transaction_begin(3) and vproc_transaction_end(3) to track outstanding transactions that need to be reconciled before the process can safely terminate. If no outstanding transactions are in progress, then launchd is free to send the SIGKILL signal.

Type: null or boolean

Default: null

Declared by:

This optional key is used to specify additional environment variables to be set before running the job.

Type: null or (attribute set of string)

Default: null

Declared by:

The amount of time launchd waits before sending a SIGKILL signal. The default value is 20 seconds. The value zero is interpreted as infinity.

Type: null or signed integer

Default: null

Declared by:

This optional key specifies the group to run the job as. This key is only applicable when launchd is running as root. If UserName is set and GroupName is not, the the group will be set to the default group of the user.

Type: null or string

Default: null

Declared by:

Resource limits to be imposed on the job. These adjust variables set with setrlimit(2). The following keys apply:

Type: null or (submodule)

Default: null

Example:

{
  NumberOfFiles = 4096;
}

Declared by:

The maximum amount of cpu time (in seconds) to be used by each process.

Type: null or signed integer

Default: null

Declared by:

The largest size (in bytes) core file that may be created.

Type: null or signed integer

Default: null

Declared by:

The maximum size (in bytes) of the data segment for a process; this defines how far a program may extend its break with the sbrk(2) system call.

Type: null or signed integer

Default: null

Declared by:

The largest size (in bytes) file that may be created.

Type: null or signed integer

Default: null

Declared by:

The maximum size (in bytes) which a process may lock into memory using the mlock(2) function.

Type: null or signed integer

Default: null

Declared by:

The maximum number of open files for this process. Setting this value in a system wide daemon will set the sysctl(3) kern.maxfiles (SoftResourceLimits) or kern.maxfilesperproc (HardResourceLimits) value in addition to the setrlimit(2) values.

Type: null or signed integer

Default: null

Declared by:

The maximum number of simultaneous processes for this user id. Setting this value in a system wide daemon will set the sysctl(3) kern.maxproc (SoftResourceLimits) or kern.maxprocperuid (HardResourceLimits) value in addition to the setrlimit(2) values.

Type: null or signed integer

Default: null

Declared by:

The maximum size (in bytes) to which a process's resident set size may grow. This imposes a limit on the amount of physical memory to be given to a process; if memory is tight, the system will prefer to take memory from processes that are exceeding their declared resident set size.

Type: null or signed integer

Default: null

Declared by:

The maximum size (in bytes) of the stack segment for a process; this defines how far a program's stack segment may be extended. Stack extension is performed automatically by the system.

Type: null or signed integer

Default: null

Declared by:

This optional key specifies whether initgroups(3) should be called before running the job. The default is true in 10.5 and false in 10.4. This key will be ignored if the UserName key is not set.

Type: null or boolean

Default: null

Declared by:

This optional key is used to control whether your job is to be kept continuously running or to let demand and conditions control the invocation. The default is false and therefore only demand will start the job. The value may be set to true to unconditionally keep the job alive. Alternatively, a dictionary of conditions may be specified to selectively control whether launchd keeps a job alive or not. If multiple keys are provided, launchd ORs them, thus providing maximum flexibility to the job to refine the logic and stall if necessary. If launchd finds no reason to restart the job, it falls back on demand based invocation. Jobs that exit quickly and frequently when configured to be kept alive will be throttled to converve system resources.

Type: null or boolean or (submodule)

Default: null

Declared by:

This required key uniquely identifies the job to launchd.

Type: string

Declared by:

Specifies higher-level event types to be used as launch-on-demand event sources. Each sub-dictionary defines events for a particular event subsystem, such as "com.apple.iokit.matching", which can be used to launch jobs based on the appearance of nodes in the IORegistry. Each dictionary within the sub-dictionary specifies an event descriptor that is specified to each event subsystem. With this key, the job promises to use the xpc_set_event_stream_handler(3) API to consume events. See xpc_events(3) for more details on event sources.

Type: null or (attribute set)

Default: null

Example:

{
  "com.apple.iokit.matching" = {
    "com.apple.usb.device" = {
      IOMatchLaunchStream = true;
      IOProviderClass = "IOUSBDevice";
      idProduct = "*";
      idVendor = "*";
    };
  };
}

Declared by:

This optional key specifies whether the job can only be run once and only once. In other words, if the job cannot be safely respawned without a full machine reboot, then set this key to be true.

Type: null or boolean

Default: null

Declared by:

This configuration file only applies to hosts NOT listed with this key. Note: One should set kern.hostname in sysctl.conf(5) for this feature to work reliably.

Type: null or (list of string)

Default: null

Declared by:

This configuration file only applies to the hosts listed with this key. Note: One should set kern.hostname in sysctl.conf(5) for this feature to work reliably.

Type: null or (list of string)

Default: null

Declared by:

This configuration file only applies to sessions of the type specified. This key is used in concert with the -S flag to launchctl.

Type: null or string

Default: null

Declared by:

This optional key specifies whether the kernel should consider this daemon to be low priority when doing file system I/O.

Type: null or boolean

Default: null

Declared by:

This optional key is used to specify Mach services to be registered with the Mach bootstrap sub-system. Each key in this dictionary should be the name of service to be advertised. The value of the key must be a boolean and set to true. Alternatively, a dictionary can be used instead of a simple true value. Finally, for the job itself, the values will be replaced with Mach ports at the time of check-in with launchd.

Type: null or (submodule)

Default: null

Example:

{
  ResetAtClose = true;
}

Declared by:

Reserve the name in the namespace, but cause bootstrap_look_up() to fail until the job has checked in with launchd.

Type: null or boolean

Default: null

Declared by:

If this boolean is false, the port is recycled, thus leaving clients to remain oblivious to the demand nature of job. If the value is set to true, clients receive port death notifications when the job lets go of the receive right. The port will be recreated atomically with respect to bootstrap_look_up() calls, so that clients can trust that after receiving a port death notification, the new port will have already been recreated. Setting the value to true should be done with care. Not all clients may be able to handle this behavior. The default value is false.

Type: null or boolean

Default: null

Declared by:

This optional key specifies what nice(3) value should be applied to the daemon.

Type: null or signed integer

Default: null

Declared by:

This key was used in Mac OS X 10.4 to control whether a job was kept alive or not. The default was true. This key has been deprecated and replaced in Mac OS X 10.5 and later with the more powerful KeepAlive option.

Type: null or boolean

Default: null

Declared by:

This optional key describes, at a high level, the intended purpose of the job. The system will apply resource limits based on what kind of job it is. If left unspecified, the system will apply light resource limits to the job, throttling its CPU usage and I/O bandwidth. The following are valid values: Background Background jobs are generally processes that do work that was not directly requested by the user. The resource limits applied to Background jobs are intended to prevent them from disrupting the user experience. Standard Standard jobs are equivalent to no ProcessType being set. Adaptive Adaptive jobs move between the Background and Interactive classifications based on activity over XPC connections. See xpc_transaction_begin(3) for details. Interactive Interactive jobs run with the same resource limitations as apps, that is to say, none. Interactive jobs are critical to maintaining a responsive user experience, and this key should only be used if an app's ability to be responsive depends on it, and cannot be made Adaptive.

Type: null or one of "Background", "Standard", "Adaptive", "Interactive"

Default: null

Example: "Background"

Declared by:

This key maps to the first argument of execvp(3). If this key is missing, then the first element of the array of strings provided to the ProgramArguments will be used instead. This key is required in the absence of the ProgramArguments key.

Type: null or path

Default: null

Declared by:

This key maps to the second argument of execvp(3). This key is required in the absence of the Program key. Please note: many people are confused by this key. Please read execvp(3) very carefully!

Type: null or (list of string)

Default: null

Declared by:

Much like the WatchPaths option, this key will watch the paths for modifications. The difference being that the job will only be started if the path is a directory and the directory is not empty.

Type: null or (list of string)

Default: null

Declared by:

This optional key is used to specify a directory to chroot(2) to before running the job.

Type: null or string

Default: null

Declared by:

This optional key is used to control whether your job is launched once at the time the job is loaded. The default is false.

Type: null or boolean

Default: null

Declared by:

This optional key is used to specify launch on demand sockets that can be used to let launchd know when to run the job. The job must check-in to get a copy of the file descriptors using APIs outlined in launch(3). The keys of the top level Sockets dictionary can be anything. They are meant for the application developer to use to differentiate which descriptors correspond to which application level protocols (e.g. http vs. ftp vs. DNS...). At check-in time, the value of each Sockets dictionary key will be an array of descriptors. Daemon/Agent writers should consider all descriptors of a given key to be to be effectively equivalent, even though each file descriptor likely represents a different networking protocol which conforms to the criteria specified in the job configuration file. The parameters below are used as inputs to call getaddrinfo(3).

Type: null or (attribute set of (submodule))

Default: null

Declared by:

This optional key can be used to request that the service be registered with the mDNSResponder(8). If the value is boolean, the service name is inferred from the SockServiceName.

Type: null or boolean or list of string

Default: null

Declared by:

This optional key can be used to request that the datagram socket join a multicast group. If the value is a hostname, then getaddrinfo(3) will be used to join the correct multicast address for a given socket family. If an explicit IPv4 or IPv6 address is given, it is required that the SockFamily family also be set, otherwise the results are undefined.

Type: null or string

Default: null

Declared by:

This optional key is a variant of SockPathName. Instead of binding to a known path, a securely generated socket is created and the path is assigned to the environment variable that is inherited by all jobs spawned by launchd.

Type: null or string

Default: null

Declared by:

This optional key can be used to specifically request that "IPv4" or "IPv6" socket(s) be created.

Type: null or one of "IPv4", "IPv6"

Default: null

Declared by:

This optional key specifies the node to connect(2) or bind(2) to.

Type: null or string

Default: null

Declared by:

This optional key specifies whether listen(2) or connect(2) should be called on the created file descriptor. The default is true ("to listen").

Type: null or boolean

Default: null

Declared by:

This optional key specifies the mode of the socket. Known bug: Property lists don't support octal, so please convert the value to decimal.

Type: null or signed integer

Default: null

Declared by:

This optional key implies SockFamily is set to "Unix". It specifies the path to connect(2) or bind(2) to.

Type: null or path

Default: null

Declared by:

This optional key specifies the protocol to be passed to socket(2). The only value understood by this key at the moment is "TCP".

Type: null or value "TCP" (singular enum)

Default: null

Declared by:

This optional key specifies the service on the node to connect(2) or bind(2) to.

Type: null or string

Default: null

Declared by:

This optional key tells launchctl what type of socket to create. The default is "stream" and other valid values for this key are "dgram" and "seqpacket" respectively.

Type: null or one of "stream", "dgram", "seqpacket"

Default: null

Declared by:

Resource limits to be imposed on the job. These adjust variables set with setrlimit(2). The following keys apply:

Type: null or (submodule)

Default: null

Declared by:

The maximum amount of cpu time (in seconds) to be used by each process.

Type: null or signed integer

Default: null

Declared by:

The largest size (in bytes) core file that may be created.

Type: null or signed integer

Default: null

Declared by:

The maximum size (in bytes) of the data segment for a process; this defines how far a program may extend its break with the sbrk(2) system call.

Type: null or signed integer

Default: null

Declared by:

The largest size (in bytes) file that may be created.

Type: null or signed integer

Default: null

Declared by:

The maximum size (in bytes) which a process may lock into memory using the mlock(2) function.

Type: null or signed integer

Default: null

Declared by:

The maximum number of open files for this process. Setting this value in a system wide daemon will set the sysctl(3) kern.maxfiles (SoftResourceLimits) or kern.maxfilesperproc (HardResourceLimits) value in addition to the setrlimit(2) values.

Type: null or signed integer

Default: null

Declared by:

The maximum number of simultaneous processes for this user id. Setting this value in a system wide daemon will set the sysctl(3) kern.maxproc (SoftResourceLimits) or kern.maxprocperuid (HardResourceLimits) value in addition to the setrlimit(2) values.

Type: null or signed integer

Default: null

Declared by:

The maximum size (in bytes) to which a process's resident set size may grow. This imposes a limit on the amount of physical memory to be given to a process; if memory is tight, the system will prefer to take memory from processes that are exceeding their declared resident set size.

Type: null or signed integer

Default: null

Declared by:

The maximum size (in bytes) of the stack segment for a process; this defines how far a program's stack segment may be extended. Stack extension is performed automatically by the system.

Type: null or signed integer

Default: null

Declared by:

This optional key specifies what file should be used for data being sent to stderr when using stdio(3).

Type: null or path

Default: null

Declared by:

This optional key specifies what file should be used for data being supplied to stdin when using stdio(3).

Type: null or path

Default: null

Declared by:

This optional key specifies what file should be used for data being sent to stdout when using stdio(3).

Type: null or path

Default: null

Declared by:

This optional key causes the job to be started every calendar interval as specified. Missing arguments are considered to be wildcard. The semantics are much like crontab(5). Unlike cron which skips job invocations when the computer is asleep, launchd will start the job the next time the computer wakes up. If multiple intervals transpire before the computer is woken, those events will be coalesced into one event upon wake from sleep.

Type: null or (list of (submodule))

Default: null

Example:

{
  Hour = 2;
  Minute = 30;
}

Declared by:

The day on which this job will be run.

Type: null or signed integer

Default: null

Declared by:

The hour on which this job will be run.

Type: null or signed integer

Default: null

Declared by:

The minute on which this job will be run.

Type: null or signed integer

Default: null

Declared by:

The month on which this job will be run.

Type: null or signed integer

Default: null

Declared by:

The weekday on which this job will be run (0 and 7 are Sunday).

Type: null or signed integer

Default: null

Declared by:

This optional key causes the job to be started every N seconds. If the system is asleep, the job will be started the next time the computer wakes up. If multiple intervals transpire before the computer is woken, those events will be coalesced into one event upon wake from sleep.

Type: null or signed integer

Default: null

Declared by:

This optional key causes the job to be started every time a filesystem is mounted.

Type: null or boolean

Default: null

Declared by:

This key lets one override the default throttling policy imposed on jobs by launchd. The value is in seconds, and by default, jobs will not be spawned more than once every 10 seconds. The principle behind this is that jobs should linger around just in case they are needed again in the near future. This not only reduces the latency of responses, but it encourages developers to amortize the cost of program invocation.

Type: null or signed integer

Default: null

Declared by:

The recommended idle time out (in seconds) to pass to the job. If no value is specified, a default time out will be supplied by launchd for use by the job at check in time.

Type: null or signed integer

Default: null

Declared by:

This optional key specifies what value should be passed to umask(2) before running the job. Known bug: Property lists don't support octal, so please convert the value to decimal.

Type: null or signed integer

Default: null

Declared by:

This optional key specifies the user to run the job as. This key is only applicable when launchd is running as root.

Type: null or string

Default: null

Declared by:

This optional key specifies that launchd should instruct the kernel to have the job wait for a debugger to attach before any code in the job is executed.

Type: null or boolean

Default: null

Declared by:

This optional key causes the job to be started if any one of the listed paths are modified.

Type: null or (list of path)

Default: null

Declared by:

This optional key is used to specify a directory to chdir(2) to before running the job.

Type: null or string

Default: null

Declared by:

The presence of this key specifies that the daemon expects to be run as if it were launched from inetd.

Type: null or (submodule)

Default: null

Example:

{
  Wait = true;
}

Declared by:

This flag corresponds to the "wait" or "nowait" option of inetd. If true, then the listening socket is passed via the standard in/out/error file descriptors. If false, then accept(2) is called on behalf of the job, and the result is passed via the standard in/out/error descriptors.

Type: null or boolean or string

Default: null

Declared by: