prune.cfg

title: prune.cfg(5)

summary: Prune Job Configuration

text:
# prune.cfg(5)

## NAME
prune.cfg - Prune Job Configuration

## DESCRIPTION
The file /etc/proxmox-backup/prune.cfg is a configuration file for Proxmox Backup Server. It contains the prune job configuration.

## FILE FORMAT
Each entry starts with the header prune: <name>, followed by the job configuration options.

```
prune: prune-store2

      schedule mon..fri 10:30

      store my-datastore
prune: ...
```

You can use the proxmox-backup-manager prune-job command to manipulate this file.

## OPTIONS
Required properties:

schedule (<calendar-event>)

Run prune job at specified schedule.

store (<string>)

Datastore name.

Optional properties:

comment (<string>)

Comment.

disable (<boolean> (default=false))

Disable this job.

max-depth (<integer> (0 - 7))

How many levels of namespaces should be operated on (0 == no recursion, empty == automatic full recursion, namespace depths reduce maximum allowed value)

ns (<string>)

Namespace.

keep-daily (<integer> (1 - N))

Number of daily backups to keep.

keep-hourly (<integer> (1 - N))

Number of hourly backups to keep.

keep-last (<integer> (1 - N))

Number of backups to keep.

keep-monthly (<integer> (1 - N))

Number of monthly backups to keep.

keep-weekly (<integer> (1 - N))

Number of weekly backups to keep.

keep-yearly (<integer> (1 - N))

Number of yearly backups to keep.

## COPYRIGHT AND DISCLAIMER
Copyright (C) 2019-2025, Proxmox Server Solutions GmbH

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License along with this program. If not, see <http://www.gnu.org/licenses/>

## Author
Proxmox Support Team

## Copyright
2019-2025, Proxmox Server Solutions GmbH


remote.cfg

package: proxmox-backup-server

title: remote.cfg(5)

summary: Remote Server Configuration

text:
# remote.cfg(5)

## NAME
remote.cfg - Remote Server Configuration

## DESCRIPTION
The file /etc/proxmox-backup/remote.cfg is a configuration file for Proxmox Backup Server. It contains information about remote servers, usable for synchronization jobs.

## FILE FORMAT
This file contains information used to access remote servers.

Each entry starts with the header remote: <name>, followed by the remote configuration options.

```
remote: server1

      host server1.local

      auth-id sync@pbs

      ...
remote: ...
```

You can use the proxmox-backup-manager remote command to manipulate this file.

## OPTIONS
Required properties:

password (<string>)

Password or auth token for remote host (stored as base64 string).

auth-id (<string>)

Authentication ID

host (<string>)

DNS name or IP address.

Optional properties:

comment (<string>)

Comment.

fingerprint (<string>)

X509 certificate fingerprint (sha256).

port (<integer>)

The (optional) port

use-node-proxy (<boolean> (default=false))

Use the http proxy configuration of the node for remote connections.

## COPYRIGHT AND DISCLAIMER
Copyright (C) 2019-2025, Proxmox Server Solutions GmbH

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License along with this program. If not, see <http://www.gnu.org/licenses/>

## Author
Proxmox Support Team

## Copyright
2019-2025, Proxmox Server Solutions GmbH

branch: sisyphus


sync.cfg

title: sync.cfg(5)

summary: Synchronization Job Configuration

text:
# sync.cfg(5)

## NAME
sync.cfg - Synchronization Job Configuration

## DESCRIPTION
The file /etc/proxmox-backup/sync.cfg is a configuration file for Proxmox Backup Server. It contains the synchronization job configuration.

## FILE FORMAT
Each entry starts with the header sync: <name>, followed by the job configuration options.

```
sync: job1

      store store1

      remote-store store1

      remote lina
sync: ...
```

You can use the proxmox-backup-manager sync-job command to manipulate this file.

## OPTIONS
Required properties:

remote-store (<string>)

Datastore name.

store (<string>)

Datastore name.

Optional properties:

active-encryption-key (<string>)

ID to uniquely identify encryption/decription key

associated-key (<string>)

List of cryptographic keys associated with sync job. Can be specified more than once.

comment (<string>)

Comment.

encrypted-only (<boolean>)

Only synchronize encrypted backup snapshots, exclude others.

group-filter ([<exclude:|include:>]<type:<vm|ct|host>|group:GROUP|regex:RE>)

List of group filters. Can be specified more than once.

max-depth (<integer> (0 - 7))

How many levels of namespaces should be operated on (0 == no recursion, empty == automatic full recursion, namespace depths reduce maximum allowed value)

ns (<string>)

Namespace.

owner (<string>)

Authentication ID

remote (<string>)

Remote ID.

remote-ns (<string>)

Namespace.

remove-vanished (<boolean> (default=false))

Delete vanished backups. This remove the local copy if the remote backup was deleted.

resync-corrupt (<boolean>)

If the verification failed for a local snapshot, try to pull it again.

run-on-mount (<boolean>)

Run this job when a relevant datastore is mounted.

schedule (<calendar-event>)

Run sync job at specified schedule.

sync-direction (pull|push (default=pull))

Direction of the sync job, push or pull

transfer-last (<integer> (1 - N))

Limit transfer to last N snapshots (per group), skipping others

unmount-on-done (<boolean>)

Unmount involved removable datastore after the sync job finishes. Requires 'run-on-mount' to be enabled.

verified-only (<boolean>)

Only synchronize verified backup snapshots, exclude others.

worker-threads (<integer> (1 - 32) (default=1))

The number of worker threads to process groups in parallel.

burst-in (<string>)

Byte size with optional unit (B, KB (base 10), MB, GB, ..., KiB (base 2), MiB, Gib, ...).

burst-out (<string>)

Byte size with optional unit (B, KB (base 10), MB, GB, ..., KiB (base 2), MiB, Gib, ...).

rate-in (<string>)

Byte size with optional unit (B, KB (base 10), MB, GB, ..., KiB (base 2), MiB, Gib, ...).

rate-out (<string>)

Byte size with optional unit (B, KB (base 10), MB, GB, ..., KiB (base 2), MiB, Gib, ...).

## COPYRIGHT AND DISCLAIMER
Copyright (C) 2019-2025, Proxmox Server Solutions GmbH

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License along with this program. If not, see <http://www.gnu.org/licenses/>

## Author
Proxmox Support Team

## Copyright
2019-2025, Proxmox Server Solutions GmbH


tape-job.cfg

title: tape-job.cfg(5)

summary: Tape Job Configuration

text:
# tape-job.cfg(5)

## NAME
tape-job.cfg - Tape Job Configuration

## DESCRIPTION
The file /etc/proxmox-backup/tape-job.cfg is a configuration file for Proxmox Backup Server. It contains the tape job configuration.

## FILE FORMAT
Each entry starts with the header backup: <name>, followed by the job configuration options.

```
backup: job1

      drive hh8

      pool p4

      store store3

      schedule daily
backup: ...
```

You can use the proxmox-tape backup-job command to manipulate this file.

## OPTIONS
Required properties:

drive (<string>)

Drive Identifier.

pool (<string>)

Media pool name.

store (<string>)

Datastore name.

Optional properties:

comment (<string>)

Comment.

schedule (<calendar-event>)

Run sync job at specified schedule.

eject-media (<boolean>)

Eject media upon job completion.

export-media-set (<boolean>)

Export media set upon job completion.

group-filter ([<exclude:|include:>]<type:<vm|ct|host>|group:GROUP|regex:RE>)

List of group filters. Can be specified more than once.

latest-only (<boolean>)

Backup latest snapshots only.

max-depth (<integer> (0 - 7) (default=7))

How many levels of namespaces should be operated on (0 == no recursion)

notification-mode (legacy-sendmail|notification-system (default=notification-system))

Configure how notifications for this datastore should be sent. legacy- sendmail sends email notifications to the user configured in notify-user via the system's sendmail executable. notification-system emits matchable notification events to the notification system.

notify-user (<string>)

User ID

ns (<string>)

Namespace.

worker-threads (<integer> (1 - 32) (default=1))

The number of threads to use for the tape backup job.

## COPYRIGHT AND DISCLAIMER
Copyright (C) 2019-2025, Proxmox Server Solutions GmbH

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License along with this program. If not, see <http://www.gnu.org/licenses/>

## Author
Proxmox Support Team

## Copyright
2019-2025, Proxmox Server Solutions GmbH


tape.cfg

title: tape.cfg(5)

summary: Tape Drive and Changer Configuration

text:
# tape.cfg(5)

## NAME
tape.cfg - Tape Drive and Changer Configuration

## DESCRIPTION
The file /etc/proxmox-backup/tape.cfg is a configuration file for Proxmox Backup Server. It contains the tape drive and changer configuration.

## FILE FORMAT
Each LTO drive configuration section starts with the header lto: <name>, followed by the drive configuration options.

Tape changer configurations start with the header changer: <name>, followed by the changer configuration options.

```
lto: hh8

      changer sl3

      path /dev/tape/by-id/scsi-10WT065325-nst
changer: sl3

      export-slots 14,15,16

      path /dev/tape/by-id/scsi-CJ0JBE0059
```

You can use the proxmox-tape drive and proxmox-tape changer commands to manipulate this file.

Note:

The virtual: drive type is experimental and should only be used for debugging.

## OPTIONS
Section type 'changer': SCSI tape changer

Required properties:

path (<string>)

Path to Linux generic SCSI device (e.g. '/dev/sg4')

Optional properties:

eject-before-unload (<boolean> (default=false))

if set to true, tapes are ejected manually before unloading

export-slots ([<integer>, ...])

A list of slot numbers, comma separated. Those slots are reserved for Import/ Export, i.e. any media in those slots are considered to be 'offline'.

Section type 'lto': Lto SCSI tape driver

Required properties:

path (<string>)

The path to a LTO SCSI-generic tape device (i.e. '/dev/sg0')

Optional properties:

changer (<string>)

Tape Changer Identifier.

changer-drivenum (<integer> (0 - 255) (default=0))

Associated changer drive number (requires option changer)

Section type 'virtual': Simulate tape drives (only for test and debug)

Required properties:

path (<string>)

Path to directory

Optional properties:

max-size (<integer> (0 - N))

Virtual tape size

## COPYRIGHT AND DISCLAIMER
Copyright (C) 2019-2025, Proxmox Server Solutions GmbH

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License along with this program. If not, see <http://www.gnu.org/licenses/>

## Author
Proxmox Support Team

## Copyright
2019-2025, Proxmox Server Solutions GmbH


user.cfg

title: user.cfg(5)

summary: User Configuration

text:
# user.cfg(5)

## NAME
user.cfg - User Configuration

## DESCRIPTION
The file /etc/proxmox-backup/user.cfg is a configuration file for Proxmox Backup Server. It contains the user configuration.

## FILE FORMAT
This file contains the list of API users and API tokens.

Each user configuration section starts with the header user: <name>, followed by the user configuration options.

API token configuration starts with the header token: <userid!token_name>, followed by the token configuration. The data used to authenticate tokens is stored in a separate file (token.shadow).

```
user: root@pam

      comment Superuser

      email test@example.local

      ...
token: root@pam!token1

      comment API test token

      enable true

      expire 0
user: ...
```

You can use the proxmox-backup-manager user command to manipulate this file.

## OPTIONS
Section type 'token': ApiToken properties.

Optional properties:

comment (<string>)

Comment.

enable (<boolean> (default=true))

Enable the account (default). You can set this to '0' to disable the account.

expire (<integer> (0 - N) (default=0))

Account expiration date (seconds since epoch). '0' means no expiration date.

Section type 'user': User properties.

Optional properties:

comment (<string>)

Comment.

email (<string>)

E-Mail Address.

enable (<boolean> (default=true))

Enable the account (default). You can set this to '0' to disable the account.

expire (<integer> (0 - N) (default=0))

Account expiration date (seconds since epoch). '0' means no expiration date.

firstname (<string>)

First name.

lastname (<string>)

Last name.

## COPYRIGHT AND DISCLAIMER
Copyright (C) 2019-2025, Proxmox Server Solutions GmbH

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License along with this program. If not, see <http://www.gnu.org/licenses/>

## Author
Proxmox Support Team

## Copyright
2019-2025, Proxmox Server Solutions GmbH


verification.cfg

title: verification.cfg(5)

summary: Verification Job Configuration

text:
# verification.cfg(5)

## NAME
verification.cfg - Verification Job Configuration

## DESCRIPTION
The file /etc/proxmox-backup/verification.cfg is a configuration file for Proxmox Backup Server. It contains the verification job configuration.

## FILE FORMAT
Each entry starts with the header verification: <name>, followed by the job configuration options.

```
verification: verify-store2

      ignore-verified true

      outdated-after 7

      schedule daily

      store store2
verification: ...
```

You can use the proxmox-backup-manager verify-job command to manipulate this file.

## OPTIONS
Required properties:

store (<string>)

Datastore name.

Optional properties:

comment (<string>)

Comment.

ignore-verified (<boolean> (default=true))

Do not verify backups that are already verified if their verification is not outdated.

max-depth (<integer> (0 - 7) (default=7))

How many levels of namespaces should be operated on (0 == no recursion)

ns (<string>)

Namespace.

outdated-after (<integer> (0 - N))

Days after that a verification becomes outdated. (0 is deprecated)'

read-threads (<integer> (1 - 32) (default=1))

The number of threads to use for reading chunks in verify job.

schedule (<calendar-event>)

Run verify job at specified schedule.

verify-threads (<integer> (1 - 32) (default=4))

The number of threads to use for verifying chunks in verify job.

## COPYRIGHT AND DISCLAIMER
Copyright (C) 2019-2025, Proxmox Server Solutions GmbH

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License along with this program. If not, see <http://www.gnu.org/licenses/>

## Author
Proxmox Support Team

## Copyright
2019-2025, Proxmox Server Solutions GmbH


remotes.cfg

package: proxmox-datacenter-manager

title: remotes.cfg(5)

text:
# remotes.cfg(5)

## NAME
remotes.cfg - Proxmox Datacenter Manager Remotes Configuration

## DESCRIPTION
The file /etc/proxmox-datacenter-manager/remotes.cfg is a configuration file for Proxmox Datacenter Manager. It contains all Proxmox VE and Proxmox Backup Server remotes that the PDM instances manages.

## OPTIONS
Section type 'pbs': The information required to connect to a remote instance.

Required properties:

authid (<string>)

Authentication ID

nodes (<string>)

A list of cluster node addresses. Can be specified more than once.

token (<string>)

The access token's secret.

type (pve|pbs (default=pve))

The type of a remote entry.

Optional properties:

web-url (<string>)

Configuration for the Web UI URL link generation.

Section type 'pve': The information required to connect to a remote instance.

Required properties:

authid (<string>)

Authentication ID

nodes (<string>)

A list of cluster node addresses. Can be specified more than once.

token (<string>)

The access token's secret.

type (pve|pbs (default=pve))

The type of a remote entry.

Optional properties:

web-url (<string>)

Configuration for the Web UI URL link generation.

## COPYRIGHT AND DISCLAIMER
Copyright (C) 2023 - 2026, Proxmox Server Solutions GmbH

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License along with this program. If not, see <http://www.gnu.org/licenses/>

## Author
Proxmox Support Team

## Copyright
2023 - 2026, Proxmox Server Solutions GmbH


views.cfg

title: views.cfg(5)

text:
# views.cfg(5)

## NAME
views.cfg - Proxmox Datacenter Manager Views Configuration

## DESCRIPTION
The file /etc/proxmox-datacenter-manager/views.cfg is a configuration file for Proxmox Datacenter Manager and is used to configure the customizable views. It contains the exclude-include filters and layout definition of each view

## OPTIONS
Optional properties:

exclude ([exact:]resource-type=<storage|qemu|lxc|sdn-zone|datastore|node>|[exact:]resource-pool=<pool-name>|[exact:]tag=<tag-name>|[exact:]remote=<remote-name>|[exact:]resource=id:<resource-id>)

List of filter rules. Can be specified more than once.

include ([exact:]resource-type=<storage|qemu|lxc|sdn-zone|datastore|node>|[exact:]resource-pool=<pool-name>|[exact:]tag=<tag-name>|[exact:]remote=<remote-name>|[exact:]resource=id:<resource-id>)

List of filter rules. Can be specified more than once.

include-all (<boolean>)

Include all resources by default.

layout (<string>)

The configured layout, encoded as json

## COPYRIGHT AND DISCLAIMER
Copyright (C) 2023 - 2026, Proxmox Server Solutions GmbH

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License along with this program. If not, see <http://www.gnu.org/licenses/>

## Author
Proxmox Support Team

## Copyright
2023 - 2026, Proxmox Server Solutions GmbH


lei-mail-formats

package: public-inbox

title: lei-mail-formats(5)

text:
# lei-mail-formats(5)

## NAME
lei-mail-formats - description of mail formats supported by lei

## DESCRIPTION
lei-q(1) supports writing to several existing mail formats for interoperability with existing mail user agents (MUA); below is an overview of them to help users choose.

## Maildir
The default output format when given a filesystem path, it supports parallel read-write access. Performance is acceptable for smaller directories, but degrades as mailboxes get larger. Speed and scalability are limited by kernel and filesystem performance due to the use of small files and large number of syscalls.

See also: <https://cr.yp.to/proto/maildir.html> and <https://wiki2.dovecot.org/MailboxFormat/Maildir>

## Mbox family
The mbox family consists of several incompatible formats. Locking for parallel access is supported, but may not be compatible across tools. With compression (e.g. gzip(1)), they require the least amount of space while offering good read-only performance.

Keyword updates ("Status:" and/or "X-Status:" headers) generally require rewriting the entire mbox.

See also: <https://www.loc.gov/preservation/digital/formats/fdd/fdd000383.shtml>, mbox(5)

### mboxo
The traditional BSD format. It quotes "From " to ">From ", but lines already beginning with ">From " do not get quoted, thus automatic reversibility is not guaranteed. MUAs which favor "mboxcl" or "mboxcl2" may convert these automatically to their preferred format.

Truncation is undetectable unless compressed with gzip or similar.

### mboxrd
An evolution of "mboxo", but quotes "From " lines prefixed with any number of ">" characters and is thus fully reversible.

This format is emitted by PublicInbox::WWW(3pm) with gzip. Since git 2.10, "git am --patch-format=mboxrd" reads this format. "git log" and "git format-patch --stdout" can also generate this format with the "--pretty=mboxrd" switch.

As with uncompressed "mboxo", uncompressed mboxrd are vulnerable to undetectable truncation.

It gracefully degrades to being treated as "mboxo" by MUAs unaware of the format as excessive ">From " quoting is recognizable to humans.

### mboxcl
"mboxo" with a "Content-Length:" header, "From " lines remain quoted to retain readability with "mboxo" and "mboxrd" MUAs. However, it is easy to corrupt these files when using tools which are not aware of "Content-Length:" and write out updates as "mboxo".

mutt(1) will convert "mboxo" and "mboxrd" to mboxcl upon opening.

See also: <https://www.jwz.org/doc/content-length.html>

### mboxcl2
Like "mboxcl", but without "From " any quoting. It is wholly incompatible with MUAs which only handle "mboxo" and/or "mboxrd". This is format is generated by mutt(1) when writing to a new mbox.

## MH
Not yet supported, locking semantics (or lack thereof) appear to make it unsuitable for parallel access. It is widely-supported by a variety of MUAs and mailing list managers, however.

## MMDF
Not yet supported, and it's unclear if current usage/support makes it worth supporting.

## IMAP
Depending on the IMAP server software and configuration, IMAP servers may use any (or combination) of the aforementioned formats or a non-standard database backend. Currently, lei uses Mail::IMAPClient which has acceptable performance over low-latency links. Performance over high-latency links is currently poor.

## eml
A single raw message file. "eml" is not an output format for lei, but accepted by as an "--input-format" ("-F") for read-only commands such as lei-tag(1) and lei-import(1).

Since "eml" is the suffix for the "message/rfc822" MIME type (according to the "mime.types" file), lei will infer the type based on the ".eml" suffix if "--input-format" is unspecified

".patch"-suffixed files generated by git-format-patch(1) (without "--stdout") are "eml" files with the addition of an mbox "From " header. lei(1) removes "From " lines to treat them as "eml" when reading these for compatibility with "git-am(1)" and similar tools.

## COPYRIGHT
Copyright 2021 all contributors <mailto:meta@public-inbox.org>

License: AGPL-3.0+ <http://www.gnu.org/licenses/agpl-3.0.txt>

## SEE ALSO
lei(1), lei-q(1), lei-convert(1), lei-overview(7)


lei-store-format

title: lei-store-format(5)

summary: lei/store format description

text:
# lei-store-format(5)

## NAME
lei-store-format - lei/store format description

## DESCRIPTION
"lei/store" is a hybrid store based on public-inbox-extindex-format(5) ("extindex") combined with public-inbox-v2-format(5) ("v2") for blob storage. While v2 is ideal for archiving a single public mailing list; it was never intended for personal mail nor storing multiple blobs of the "same" message.

As with extindex, it can index disparate "List-Id" headers belonging to the "same" message with different git blob OIDs. Unlike v2 and extindex, "Message-ID" headers are NOT required; allowing unsent draft messages to be stored and indexed.

## DIRECTORY LAYOUT
Blob storage exists in the form of v2-style epochs. These epochs are under the "local/" directory (instead of "git/") to prevent them from being accidentally treated as a v2 inbox.

### INDEX OVERVIEW AND DEFINITIONS

```
  $EPOCH - Integer starting with 0 based on time
  $SCHEMA_VERSION - DB schema version (for Xapian)
  $SHARD - Integer starting with 0 based on parallelism
  ~/.local/share/lei/store
  - local/$EPOCH.git                # normal bare git repositories
  - mail_sync.sqlite3               # sync state IMAP, Maildir, NNTP
```

Additionally, the following share the same roles they do in extindex:

```
  - ei.lock                         # lock file to protect global state
  - ALL.git                         # empty, alternates for local/*.git
  - ei$SCHEMA_VERSION/$SHARD        # per-shard Xapian DB
  - ei$SCHEMA_VERSION/over.sqlite3  # overview DB for WWW, IMAP
  - ei$SCHEMA_VERSION/misc          # misc Xapian DB
```

### XREF3 DEDUPLICATION
Index deduplication follows extindex, see "XREF3 DEDUPLICATION" in public-inbox-extindex-format(5) for more information.

### BLOB DEDUPLICATION
The contents of "local/*.git" repos is deduplicated by git blob object IDs (currently SHA-1). This allows multiple copies of cross-posted and personally Cc-ed messages to be stored with different "Received:", "X-Spam-Status:" and similar headers to allow troubleshooting.

### VOLATILE METADATA
Keywords and label information (as described in RFC 8621 for JMAP) is stored in existing Xapian shards ("ei$SCHEMA_VERSION/$SHARD"). It is possible to search for messages matching labels and keywords using "L:" and "kw:", respectively. As with all data stored in Xapian indices, volatile metadata is associated with the Xapian document, thus it is shared across different blobs of the "same" message.

### mail_sync.sqlite3
This SQLite database is maintained for bidirectional mapping of git blobs to IMAP UIDs, Maildir file names, and NNTP article numbers.

It is also used for retrieving messages from Maildirs indexed by lei-index(1).

## IPC
lei-daemon(8) communicates with the "lei/store" process using unix(7) "SOCK_SEQPACKET" sockets.

## CAVEATS
Reindexing and synchronization is not yet supported.

## THANKS
Thanks to the Linux Foundation for sponsoring the development and testing.

## COPYRIGHT
Copyright 2021 all contributors <mailto:meta@public-inbox.org>

License: AGPL-3.0+ <http://www.gnu.org/licenses/agpl-3.0.txt>

## SEE ALSO
public-inbox-v2-format(5), public-inbox-extindex(5)


public-inbox-config

title: public-inbox-config(5)

summary: public\-inbox config file description

text:
# public-inbox-config(5)

## NAME
public-inbox-config - public-inbox config file description

## SYNOPSIS
~/.public-inbox/config

## DESCRIPTION
The public-inbox config file is parseable by git-config(1). This is a global configuration file for mapping/discovering all public-inboxes used by a particular user.

## CONFIGURATION FILE

### EXAMPLE

```
        [publicinbox "test"]
                inboxdir = /home/user/path/to/test.git
                ; multiple addresses are supported
                address = test@example.com
                ; address = alternate@example.com
                url = http://example.com/test
                newsgroup = inbox.test
                ; backwards compatibility with public-inbox pre-1.2.0,
                ; "inboxdir" takes precedence over "mainrepo"
                mainrepo = /home/user/path/to/test.git
```

### VARIABLES
publicinbox.<name>.address

The email address of the public-inbox. May be specified more than once for merging multiple mailing lists (or migrating to new addresses). This must be specified at least once, the first value will be considered the primary address for informational purposes. Default: none, required

publicinbox.<name>.inboxdir

The absolute path to the directory which hosts the public-inbox. This must be specified once. This was previously known as "mainrepo", which remains supported, but "inboxdir" takes precedence.

Default: none, required

publicinbox.<name>.url

The primary URL for hosting the HTTP/HTTPS archives. Additional HTTP/HTTPS URLs may be specified via "$GIT_DIR/cloneurl" as documented in gitweb(1) Default: none, optional

publicinbox.<name>.newsgroup

The NNTP group name for use with public-inbox-nntpd(1). This may be any newsgroup name with hierarchies delimited by ".". For example, the newsgroup for <mailto:meta@public-inbox.org> is: "inbox.comp.mail.public-inbox.meta" It also configures the folder hierarchy used by public-inbox-imapd(1) as well as public-inbox-pop3d(1)

Omitting this for a given inbox will prevent the inbox from being served by public-inbox-nntpd(1), public-inbox-imapd(1), and/or public-inbox-pop3d(1)

Newsgroup names should be all lowercase. Uppercase characters are converted to lowercase for compatibility with IMAP, POP3, and our public-inbox-extindex(1) and public-inbox-cindex(1) tools starting with public-inbox 2.0+ (they were unusable before).

Default: none, optional

publicinbox.<name>.watch

See public-inbox-watch(1)

publicinbox.<name>.watchheader

See public-inbox-watch(1)

publicinbox.<name>.listid

The rfc2919 <https://tools.ietf.org/html/rfc2919> header without angle brackets for public-inbox-mda(1) deliveries and public-inbox-watch(1). For public-inbox-watch users, this is a shortcut for specifying "publicinbox.$NAME.watchheader=List-Id:<foo.example.com>"

For public-inbox-mda users, this may be used to avoid recipient matching via "ORIGINAL_RECIPIENT" environment variable.

This may be specified multiple times for merging multiple mailing lists into a single public-inbox, only one "List-Id" header needs to match.

Default: none

publicinbox.<name>.imapmirror

This may be the full IMAP URL of an independently-run IMAP mirror. Default: none

publicinbox.<name>.nntpmirror

This may be the full NNTP URL of an independently-run mirror. For example, the https://public-inbox.org/meta/ inbox is mirrored by Gmane at "nntp://news.gmane.io/gmane.mail.public-inbox.general" Default: none

publicinbox.<name>.indexlevel

The indexing level for public-inbox-index(1) "basic" only requires DBD::SQLite(3pm) and provides all NNTP functionality along with thread-awareness in the WWW interface.

"medium" requires Xapian(3pm) or Search::Xapian(3pm) to provide full-text term search functionality in the WWW UI.

"full" also includes positional information used by Xapian to allow for searching for phrases using quoted text. (e.g. "looking for a complete sentence")

Default: "full"

publicinbox.<name>.boost

Control indexing order for public-inbox-extindex(1), with ties broken by config file order. This only affects indexing and does not affect messages which are already indexed. Default: 0

publicinbox.<name>.indexSequentialShard

See "publicInbox.indexSequentialShard" in public-inbox-index(1)

publicinbox.<name>.httpbackendmax

If a digit, the maximum number of parallel git-http-backend(1) processes to allow for cloning this particular inbox. If an alphanumeric value starting with a lowercase alphabetic character is specified, the inbox will use a "NAMED LIMITER" which can be shared by multiple inboxes.

Default: 32 (using a default limiter shared by all inboxes)

publicinbox.<name>.coderepo

The nickname of a "coderepo" section associated with the inbox. May be specified more than once for M:N mapping of code repos to inboxes. If enabled, diff hunk headers in patch emails will link to the line numbers of blobs. Default: none

publicinbox.<name>.replyto

May be used to control how reply instructions in the PSGI interface are displayed. ":none=dead inbox" may be specified to denote an inactive list ("dead inbox" may be replaced with another phrase).

A list of comma-delimited email addresses may be specified. This can be useful for dedicated inboxes for bot emails, but discussion happens on a separate mailing list/inbox.

Mirrors of existing centralized mailing lists may use ":list" here to redirect mail only to the configured inbox address. The use of ":list" is discouraged for new mailing lists, as it leads to centralization.

Default: :all

publicinbox.css

The local path name of a CSS file for the PSGI web interface. May contain the attributes "media", "title" and "href" which match the associated attributes of the HTML <style> tag. "href" may be specified to point to the URL of a remote CSS file and the path may be "/dev/null" or any empty file. Multiple files may be specified and will be included in the order specified.

publicinboxImport.dropUniqueUnsubscribe

Drop "List-Unsubscribe" headers if the message also includes the "List-Unsubscribe-Post: List-Unsubscribe=One-Click" header to signal MUAs to support an instantaneous unsubscribe. This is strongly recommended for users creating their own public archives of mailing lists they subscribe to, otherwise any archive reader can unsubscribe the archivist. This may break DKIM signatures if the "List-Unsubscribe*" headers are signed, but breaking DKIM signatures is the lesser evil compared to allowing any reader to unsubscribe the archivist.

This affects public-inbox-mda(1), public-inbox-watch(1), and public-inbox-learn(1)

publicinboxmda.spamcheck

This may be set to "none" to disable the use of SpamAssassin spamc(1) for filtering spam before it is imported into git history. Other spam filtering backends may be supported in the future. Default: spamc

publicinboxwatch.spamcheck

See public-inbox-watch(1)

publicinboxwatch.watchspam

See public-inbox-watch(1)

publicinbox.imapserver

Set this to point to the hostname(s) of the public-inbox-imapd(1) instance. This is used to advertise the existence of the IMAP endpoint in the PublicInbox::WWW HTML interface. Default: none

publicinbox.nntpserver

Same as "publicinbox.imapserver", but for the hostname(s) of the public-inbox-nntpd(1) instance. Default: none

publicinbox.pop3server

Same as "publicinbox.imapserver", but for the hostname(s) of the public-inbox-pop3d(1) instance. Default: none

publicinbox.pop3state

See "publicinbox.pop3state" in public-inbox-pop3d(1)

publicinbox.<name>.feedmax

The size of an Atom feed for the inbox. If specified more than once, only the last value is used. Invalid values (<= 0) will be treated as the default value. Default: 25

publicinbox.<name>.hide

A comma-delimited list of listings to hide the inbox from. Valid values are currently "www" and "manifest" for non-404 values of "publicinbox.wwwListing" and "publicinbox.grokManifest", respectively

Default: none

coderepo.<nick>.dir

The path to a git repository for "publicinbox.<name>.coderepo"

coderepo.<nick>.cgitUrl

The URL of the cgit instance associated with the coderepo. Default: none

coderepo.snapshots

See "snapshots" in cgitrc(5)

publicinbox.cgitrc

A path to a cgitrc(5) file. "repo.url" directives in the cgitrc will be mapped to the nickname of a coderepo (without trailing slash), and "repo.path" directives map to "coderepo.<nick>.dir". Use of this directive allows admins of existing cgit installations to skip declaring coderepo sections and map inboxes directly to code repositories known to cgit. Macro expansion (e.g. $HTTP_HOST) is not yet supported.

publicinbox.cgitbin

A path to the "cgit.cgi" executable. The PublicInbox::WWW interface can spawn cgit as a fallback if the publicinbox.cgitrc directive is configured. Default: /var/www/htdocs/cgit/cgit.cgi or /usr/lib/cgit/cgit.cgi

publicinbox.cgitdata

A path to the data directory used by cgit for storing static files. Typically guessed based on the location of "cgit.cgi" (from "publicinbox.cgitbin"), but may be overridden. Default: dirname of "publicinbox.cgitbin", /var/www/htdocs/cgit/ or /usr/share/cgit/

publicinbox.cgit

Controls whether or not and how "cgit" is used for serving coderepos. New in public-inbox 2.0.0 (PENDING).

- first Try using "cgit" as the first choice, this is the default.

- fallback Fall back to using "cgit" only if our native, inbox-aware git code repository viewer doesn't recognize the URL.

- rewrite Rewrite "cgit" URLs for our native, inbox-aware code repository viewer. This implies "fallback" for URLs the native viewer does not recognize.

Default: "first" ("cgit" will be used iff "publicinbox.cgitrc" is set and the "cgit" binary exists).

publicinbox.mailEditor

See public-inbox-edit(1)

publicinbox.indexMaxSize =item publicinbox.indexBatchSize =item publicinbox.indexSequentialShard

See public-inbox-index(1)

publicinbox.wwwlisting

Enable a HTML listing style when the root path of the URL '/' is accessed. Valid values are:

- all - Show all inboxes

- 404 - Return a 404 page. This is useful to allow customization with Plack::App::Cascade(3pm)

- match=domain - Only show inboxes with URLs which belong to the domain of the HTTP request

Default: 404

publicinbox.nameIsUrl

Treat the name of the public inbox as its unqualified URL when using "publicInbox.wwwListing=all". This is, every "[publicinbox "foo"]" section implicitly sets "publicinbox.foo.url=foo". This is a convenient alternative to specifying "publicinbox.<name>.url" for every single inbox if your inbox URLs are domain-agnostic when using "publicInbox.wwwListing=all"

Default: false

New in public-inbox 2.0.0 (PENDING).

publicinbox.grokmanifest

Controls the generation of a grokmirror-compatible gzipped JSON file at the top-level of the PSGI interface. You generally do not need to change this from the default. Valid values are:

- match=domain - Only include inboxes with URLs which belong to the domain of the HTTP request. This is compatible with virtual hosting where several domains come from the same host.

- all - All inboxes are present in "manifest.js.gz", regardless of domain. Only use this if you're serving HTTP requests in a domain-agnostic manner.

- 404 - "manifest.js.gz" will only contain an empty JSON array. This does NOT affect "$INBOX_URL/manifest.js.gz", which will always contain all git repos used by the inbox at $INBOX_URL

Default: "match=domain"

publicinbox.<name>.obfuscate

Whether to obfuscate email addresses in the PublicInbox::WWW HTML interface. Default: false

publicinbox.noObfuscate

A space-delimited list of well-known addresses and domains that should not be obfuscated when "publicinbox.$NAME.obfuscate" is true (e.g., "public@example.com" and "@example.com"). This may be specified more than once, in which case the values are merged. Default: none

extindex.<name>.topdir

The directory of an external index. See public-inbox-extindex(1) for more details.

extindex.<name>.url

Identical to "publicinbox.<name>.url", but for external indices

extindex.<name>.coderepo

Identical to "publicinbox.<name>.coderepo", but for external indices. Code repos may be freely associated with any number of public inboxes and external indices.

### NAMED LIMITER (PSGI)
Named limiters are useful for preventing large inboxes from monopolizing (or overloading) the server. Since serving git clones (via git-http-backend(1) can be memory-intensive for large inboxes, it makes sense to put large inboxes on a named limiter with a low max value; while smaller inboxes can use the default limiter.

"RLIMIT_*" keys may be set to enforce resource limits for a particular limiter (BSD::Resource(3pm) is required).

Default named-limiters are prefixed with "-". Currently, the "-cgit" named limiter is reserved for instances spawning cgit via "publicinbox.cgitrc"

publicinboxlimiter.<name>.max

The maximum number of parallel processes for the given limiter.

publicinboxlimiter.<name>.rlimitCore

publicinboxlimiter.<name>.rlimitCPU

publicinboxlimiter.<name>.rlimitData

The maximum core size, CPU time, or data size processes run with the given limiter will use. This may be comma-separated to distinguish soft and hard limits. The word "INFINITY" is accepted as the RLIM_INFINITY constant (if supported by your OS). See setrlimit(2) for more info on the behavior of RLIMIT_CORE, RLIMIT_CPU, and RLIMIT_DATA for you operating system.

EXAMPLE WITH NAMED LIMITERS

```
        ; big inboxes which require lots of memory to clone:
        [publicinbox "big1"]
                inboxdir = /path/to/big1
                address = big1@example.com
                httpbackendmax = big
        [publicinbox "big2"]
                inboxdir = /path/to/big2
                address = big2@example.com
                httpbackendmax = big
        ; tiny inboxes which are easily cloned:
        [publicinbox "tiny1"]
                inboxdir = /path/to/tiny1
                address = tiny1@example.com
        [publicinbox "tiny2"]
                inboxdir = /path/to/tiny2
                address = tiny2@example.com
        [publicinboxlimiter "big"]
                max = 4
```

In the above example, the "big1" and "big2" are limited to four parallel git-http-backend(1) processes between them.

However, "tiny1" and "tiny2" will share the default limiter which means there can be 32 git-http-backend(1) processes between them.

## ENVIRONMENT
PI_CONFIG

Used to override the default "~/.public-inbox/config" value.

## CONTACT
Feedback welcome via plain-text mail to <mailto:meta@public-inbox.org>

The mail archives are hosted at <https://public-inbox.org/meta/> and <http://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/meta/>

## COPYRIGHT
Copyright all contributors <mailto:meta@public-inbox.org>

License: AGPL-3.0+ <https://www.gnu.org/licenses/agpl-3.0.txt>

## SEE ALSO
git(1), git-config(1), public-inbox-daemon(8), public-inbox-mda(1), public-inbox-watch(1), grokmirror <https://git.kernel.org/pub/scm/utils/grokmirror/grokmirror.git>


public-inbox-extindex-format

title: public-inbox-extindex-format(5)

summary: external index format description

text:
# public-inbox-extindex-format(5)

## NAME
public-inbox-extindex-format - external index format description

## DESCRIPTION
The extindex is an index-only evolution of the per-inbox SQLite and Xapian indices used by public-inbox-v2-format(5) and public-inbox-v1-format(5). It exists to facilitate searches across multiple inboxes as well as to reduce index space when messages are cross-posted to several existing inboxes.

It transparently indexes messages across any combination of v1 and v2 inboxes and data about inboxes themselves.

## DIRECTORY LAYOUT
While inspired by v2, there is no git blob storage nor "msgmap.sqlite3" DB.

Instead, there is an "ALL.git" (all caps) git repo which treats every indexed v1 inbox or v2 epoch as a git alternate.

As with v2 inboxes, it uses "over.sqlite3" and Xapian "shards" for WWW and IMAP use. Several exclusive new tables are added to deal with "XREF3 DEDUPLICATION" and metadata.

Unlike v1 and v2 inboxes, it is NOT designed to map to a NNTP newsgroup. Thus it lacks "msgmap.sqlite3" to enforce the unique Message-ID requirement of NNTP.

### INDEX OVERVIEW AND DEFINITIONS

```
  $SCHEMA_VERSION - DB schema version (for Xapian)
  $SHARD - Integer starting with 0 based on parallelism
  foo/                              # "foo" is the name of the index
  - ei.lock                         # lock file to protect global state
  - ALL.git                         # empty, alternates for inboxes
  - ei$SCHEMA_VERSION/$SHARD        # per-shard Xapian DB
  - ei$SCHEMA_VERSION/over.sqlite3  # overview DB for WWW, IMAP
  - ei$SCHEMA_VERSION/misc          # misc Xapian DB
```

File and directory names are intentionally different from analogous v2 names to ensure extindex and v2 inboxes can easily be distinguished from each other.

### XREF3 DEDUPLICATION
Due to cross-posted messages being the norm in the large Linux kernel development community and Xapian indices being the primary consumer of storage, it makes sense to deduplicate indexing as much as possible.

The internal storage format is based on the NNTP "Xref" tuple, but with the addition of a third element: the git blob OID. Thus the triple is expressed in string form as:

```
        $NEWSGROUP_NAME:$ARTICLE_NUM:$OID
```

If no "newsgroup" is configured for an inbox, the "inboxdir" of the inbox is used.

This data is stored in the "xref3" table of over.sqlite3.

### misc XAPIAN DB
In addition to the numeric Xapian shards for indexing messages, there is a new, in-development Xapian index for storing data about inboxes themselves and other non-message data. This index allows us to speed up operations involving hundreds or thousands of inboxes.

## BENEFITS
In addition to providing cross-inbox search capabilities, it can also replace per-inbox Xapian shards (but not per-inbox over.sqlite3). This allows reduction in disk space, open file handles, and associated memory use.

## CAVEATS
Relocating v1 and v2 inboxes on the filesystem will require extindex to be garbage-collected and/or reindexed.

Configuring and maintaining stable "newsgroup" names before any messages are indexed from every inbox can avoid expensive reindexing and rely exclusively on GC.

## LOCKING
flock(2) locking exclusively locks the empty ei.lock file for all non-atomic operations.

## THANKS
Thanks to the Linux Foundation for sponsoring the development and testing.

## COPYRIGHT
Copyright 2020-2021 all contributors <mailto:meta@public-inbox.org>

License: AGPL-3.0+ <http://www.gnu.org/licenses/agpl-3.0.txt>

## SEE ALSO
public-inbox-v2-format(5)


title: public-inbox-v1-format(5)

summary: git repository and tree description (aka ssoma)

text:
# public-inbox-v1-format(5)

## NAME
public-inbox-v1-format - git repository and tree description (aka "ssoma")

## DESCRIPTION
WARNING: this does NOT describe the scalable v2 format used by public-inbox. Use of ssoma is not recommended for new installations due to scalability problems.

ssoma uses a git repository to store each email as a git blob. The tree filename of the blob is based on the SHA1 hexdigest of the first Message-ID header. A commit is made for each message delivered. The commit SHA-1 identifier is used by ssoma clients to track synchronization state.

## PATHNAMES IN TREES
A Message-ID may be extremely long and also contain slashes, so using them as a path name is challenging. Instead we use the SHA-1 hexdigest of the Message-ID (excluding the leading "<" and trailing ">") to generate a path name. Leading and trailing white space in the Message-ID header is ignored for hashing.

A message with Message-ID of: <20131106023245.GA20224@dcvr.yhbt.net>

Would be stored as: f2/8c6cfd2b0a65f994c3e1be266105413b3d3f63

Thus it is easy to look up the contents of a message matching a given a Message-ID.

## MESSAGE-ID CONFLICTS
public-inbox v1 repositories currently do not resolve conflicting Message-IDs or messages with multiple Message-IDs.

## HEADERS
The Message-ID header is required. "Bytes", "Lines" and "Content-Length" headers are stripped and not allowed, they can interfere with further processing. When using ssoma with public-inbox-mda, the "Status" mbox header is also stripped as that header makes no sense in a public archive.

## LOCKING
flock(2) locking exclusively locks the empty $GIT_DIR/ssoma.lock file for all non-atomic operations.

## EXAMPLE INPUT FLOW (SERVER-SIDE MDA)
1. Message is delivered to a mail transport agent (MTA)

1a. (optional) reject/discard spam, this should run before ssoma-mda

1b. (optional) reject/strip unwanted attachments

ssoma-mda handles all steps once invoked.

2. Mail transport agent invokes ssoma-mda

3. reads message via stdin, extracting Message-ID

4. acquires exclusive flock lock on $GIT_DIR/ssoma.lock

5. creates or updates the blob of associated 2/38 SHA-1 path

6. updates the index and commits

7. releases $GIT_DIR/ssoma.lock

ssoma-mda can also be used as an inotify(7) trigger to monitor maildirs, and the ability to monitor IMAP mailboxes using IDLE will be available in the future.

## GIT REPOSITORIES (SERVERS)
ssoma uses bare git repositories on both servers and clients.

Using the git-init(1) command with --bare is the recommend method of creating a git repository on a server:

```
        git init --bare /path/to/wherever/you/want.git
```

There are no standardized paths for servers, administrators make all the choices regarding git repository locations.

Special files in $GIT_DIR on the server:

$GIT_DIR/ssoma.lock

An empty file for flock(2) locking. This is necessary to ensure the index and commits are updated consistently and multiple processes running MDA do not step on each other.

$GIT_DIR/public-inbox/msgmap.sqlite3

SQLite3 database maintaining a stable mapping of Message-IDs to NNTP article numbers. Used by public-inbox-nntpd(1) and created and updated by public-inbox-index(1). Users of the PublicInbox::WWW interface will find it useful for attempting recovery from copy-paste truncations of URLs containing long Message-IDs.

Automatically updated by public-inbox-mda(1), public-inbox-learn(1) and public-inbox-watch(1).

Losing or damaging this file will cause synchronization problems for NNTP clients. This file is expected to be stable and require no updates to its schema.

Requires DBD::SQLite.

$GIT_DIR/public-inbox/xapian$N/

Xapian database for search indices in the PSGI web UI. $N is the value of PublicInbox::Search::SCHEMA_VERSION, and installations may have parallel versions on disk during upgrades or to roll-back upgrades.

This is created and updated by public-inbox-index(1).

Automatically updated by public-inbox-mda(1), public-inbox-learn(1) and public-inbox-watch(1).

This directory can always be regenerated with public-inbox-index(1). If lost or damaged, there is no need to back it up unless the CPU/memory cost of regenerating it outweighs the storage/transfer cost.

Since SCHEMA_VERSION 15 and the development of the v2 format, the "overview" DB also exists in the xapian directory for v1 repositories. See "OVERVIEW DB" in public-inbox-v2-format(5)

Our use of the "OVERVIEW DB" requires Xapian document IDs to remain stable. Using public-inbox-compact(1) and public-inbox-xcpdb(1) wrappers are recommended over tools provided by Xapian.

This directory is large, often two to three times the size of the objects stored in a packed git repository.

$GIT_DIR/ssoma.index

This file is no longer used or created by public-inbox, but it is updated if it exists to remain compatible with ssoma installations. A git index file used for MDA updates. The normal git index (in $GIT_DIR/index) is not used at all as there is typically no working tree.

Each client $GIT_DIR may have multiple mbox/maildir/command targets. It is possible for a client to extract the mail stored in the git repository to multiple mboxes for compatibility with a variety of different tools.

## CAVEATS
It is NOT recommended to check out the working directory of a git. there may be many files.

It is impossible to completely expunge messages, even spam, as git retains full history. Projects may (with adequate notice) cycle to new repositories/branches with history cleaned up via git-filter-repo(1) or git-filter-branch(1). This is up to the administrators.

## COPYRIGHT
Copyright 2013-2021 all contributors <mailto:meta@public-inbox.org>

License: AGPL-3.0+ <http://www.gnu.org/licenses/agpl-3.0.txt>

## SEE ALSO
gitrepository-layout(5), ssoma(1)


title: public-inbox-v2-format(5)

summary: structure of public inbox v2 archives

text:
# public-inbox-v2-format(5)

## NAME
public-inbox-v2-format - structure of public inbox v2 archives

## DESCRIPTION
The v2 format is designed primarily to address several scalability problems of the original format described at public-inbox-v1-format(5). It also handles messages with Message-IDs.

## INBOX LAYOUT
The key change in v2 is the inbox is no longer a bare git repository, but a directory with two or more git repositories. v2 divides git repositories by time "epochs" and Xapian databases for parallelism by "shards".

### INBOX OVERVIEW AND DEFINITIONS

```
  $EPOCH - Integer starting with 0 based on time
  $SCHEMA_VERSION - DB schema version (for Xapian)
  $SHARD - Integer starting with 0 based on parallelism
  foo/                              # "foo" is the name of the inbox
  - inbox.lock                      # lock file to protect global state
  - git/$EPOCH.git                  # normal git repositories
  - all.git                         # empty, alternates to $EPOCH.git
  - xap$SCHEMA_VERSION/$SHARD       # per-shard Xapian DB
  - xap$SCHEMA_VERSION/over.sqlite3 # OVER-view DB for NNTP, threading
  - msgmap.sqlite3                  # same as the v1 msgmap
```

For blob lookups, the reader only needs to open the "all.git" repository with $GIT_DIR/objects/info/alternates which references every $EPOCH.git repo.

Individual $EPOCH.git repos DO NOT use alternates themselves as git currently limits recursion of alternates nesting depth to 5.

### GIT EPOCHS
One of the inherent scalability problems with git itself is the full history of a project must be stored and carried around to all clients. To address this problem, the v2 format uses multiple git repositories, stored as time-based "epochs".

We currently divide epochs into roughly one gigabyte segments; but this size can be configurable (if needed) in the future.

A pleasant side-effect of this design is the git packs of older epochs are stable, allowing them to be cloned without requiring expensive pack generation. This also allows clients to clone only the epochs they are interested in to save bandwidth and storage.

To minimize changes to existing v1-based code and simplify our code, we use the "alternates" mechanism described in gitrepository-layout(5) to link all the epoch repositories with a single read-only "all.git" endpoint.

Processes retrieve blobs via the "all.git" repository, while writers write blobs directly to epochs.

### GIT TREE LAYOUT
One key problem specific to v1 was large trees were frequently a performance problem as name lookups are expensive and there were limited deltafication opportunities with unpredictable file names. As a result, all Xapian-enabled installations retrieve blob object_ids directly in v1, bypassing tree lookups.

While dividing git repositories into epochs caps the growth of trees, worst-case tree size was still unnecessary overhead and worth eliminating.

So in contrast to the big trees of v1, the v2 git tree contains only a single file at the top-level of the tree, either 'm' (for 'mail' or 'message') or 'd' (for deleted). A tree does not have 'm' and 'd' at the same time.

Mail is still stored in blobs (instead of inline with the commit object) as we still need a stable reference in the indices in case commit history is rewritten to comply with legal requirements.

After-the-fact invocations of public-inbox-index will ignore messages written to 'd' after they are written to 'm'.

Deltafication is not significantly improved over v1, but overall storage for trees is made as small as possible. Initial statistics and benchmarks showing the benefits of this approach are documented at:

<https://public-inbox.org/meta/20180209205140.GA11047@dcvr/>

### XAPIAN SHARDS
Another scalability problem in v1 was the inability to utilize multiple CPU cores for Xapian indexing. This is addressed by using shards in Xapian to perform import indexing in parallel.

As with git alternates, Xapian natively supports a read-only interface which transparently abstracts away the knowledge of multiple shards. This allows us to simplify our read-only code paths.

The performance of the storage device is now the bottleneck on larger multi-core systems. In our experience, performance is improved with high-quality and high-quantity solid-state storage. Issuing TRIM commands with fstrim(8) was necessary to maintain consistent performance while developing this feature.

Rotational storage devices perform significantly worse than solid state storage for indexing of large mail archives; but are fine for backup and usable for small instances.

As of public-inbox 1.6.0, the "publicInbox.indexSequentialShard" option of public-inbox-index(1) may be used with a high shard count to ensure individual shards fit into page cache when the entire Xapian DB cannot.

Our use of the "OVERVIEW DB" requires Xapian document IDs to remain stable. Using public-inbox-compact(1) and public-inbox-xcpdb(1) wrappers are recommended over tools provided by Xapian.

### OVERVIEW DB
Towards the end of v2 development, it became apparent Xapian did not perform well for sorting large result sets used to generate the landing page in the PSGI UI (/$INBOX/) or many queries used by the NNTP server. Thus, SQLite was employed and the Xapian "skeleton" DB was renamed to the "overview" DB (after the NNTP OVER/XOVER commands).

The overview DB maintains all the header information necessary to implement the NNTP OVER/XOVER commands and non-search endpoints of the PSGI UI.

Xapian has become completely optional for v2 (as it is for v1), but SQLite remains required for v2. SQLite turns out to be powerful enough to maintain overview information. Most of the PSGI and all of the NNTP functionality is possible with only SQLite in addition to git.

The overview DB was an instrumental piece in maintaining near constant-time read performance on a dataset 2-3 times larger than LKML history as of 2018.

GHOST MESSAGES

The overview DB also includes references to "ghost" messages, or messages which have replies but have not been seen by us. Thus it is expected to have more rows than the "msgmap" DB described below.

### msgmap.sqlite3
The SQLite msgmap DB is unchanged from v1, but it is now at the top-level of the directory.

## OBJECT IDENTIFIERS
There are three distinct type of identifiers. content_hash is the new one for v2 and should make message removal and deduplication easier. object_id and Message-ID are already known.

object_id

The blob identifier git uses (currently SHA-1). No need to publicly expose this outside of normal git ops (cloning) and there's no need to make this searchable. As with v1 of public-inbox, this is stored as part of the Xapian document so expensive name lookups can be avoided for document retrieval.

Message-ID

The email header; duplicates allowed for archival purposes. This remains a searchable field in Xapian. Note: it's possible for emails to have multiple Message-ID headers (and git-send-email(1) had that bug for a bit); so we take all of them into account. In case of conflicts detected by content_hash below, we generate a new Message-ID based on content_hash; if the generated Message-ID still conflicts, a random one is generated.

content_hash

A hash of relevant headers and raw body content for purging of unwanted content. This is not stored anywhere, but always calculated on-the-fly. For now, the relevant headers are:

```
        Subject, From, Date, References, In-Reply-To, To, Cc

```

Received, List-Id, and similar headers are NOT part of content_hash as they differ across lists and we will want removal to be able to cross lists.

The textual parts of the body are decoded, CRLF normalized to LF, and trailing whitespace stripped. Notably, hashing the raw body risks being broken by list signatures; but we can use filters (e.g. PublicInbox::Filter::Vger) to clean the body for imports.

content_hash is SHA-256 for now; but can be changed at any time without making DB changes.

## LOCKING
flock(2) locking exclusively locks the empty inbox.lock file for all non-atomic operations.

## HEADERS
Same handling as with v1, except the Message-ID header will be generated if not provided or conflicting. "Bytes", "Lines" and "Content-Length" headers are stripped and not allowed, they can interfere with further processing.

The "Status" mbox header is also stripped as that header makes no sense in a public archive.

## THANKS
Thanks to the Linux Foundation for sponsoring the development and testing of the v2 format.

## COPYRIGHT
Copyright 2018-2021 all contributors <mailto:meta@public-inbox.org>

License: AGPL-3.0+ <http://www.gnu.org/licenses/agpl-3.0.txt>

## SEE ALSO
gitrepository-layout(5), public-inbox-v1-format(5)


default.pa

package: pulseaudio-daemon

title: default.pa(5)

summary: PulseAudio Sound Server Startup Script

text:
# default.pa(5)

## NAME
default.pa - PulseAudio Sound Server Startup Script

## SYNOPSIS
~/.config/pulse/default.pa

/etc/pulse/default.pa

/etc/pulse/system.pa

## DESCRIPTION
The PulseAudio sound server interprets a configuration script on startup, which is mainly used to define the set of modules to load. When PulseAudio runs in the per-user mode and ~/.config/pulse/default.pa exists, that file is used. When PulseAudio runs in the per-user mode and that file doesn't exist, /etc/pulse/default.pa is used. When PulseAudio runs as a system service, /etc/pulse/system.pa is used.

The script should contain directives in the PulseAudio CLI language, as documented in pulse-cli-syntax(5).

## AUTHORS
The PulseAudio Developers <pulseaudio-discuss (at) lists (dot) freedesktop (dot) org>; PulseAudio is available from http://pulseaudio.org/

## SEE ALSO
pulse-cli-syntax(5), pulse-daemon.conf(5), pulseaudio(1), pacmd(1)


pulse-cli-syntax

title: pulse-cli-syntax(5)

text:
# pulse-cli-syntax(5)

## NAME
pulse-cli-syntax - PulseAudio Command Line Interface Syntax

## SYNOPSIS
~/.config/pulse/default.pa

/etc/pulse/default.pa

/etc/pulse/system.pa

## DESCRIPTION
PulseAudio provides a simple command line language used by configuration scripts, the pacmd interactive shell, and the modules module-cli and module-cli-protocol-{unix,tcp}. Empty lines and lines beginning with a hashmark (#) are silently ignored. Several commands are supported.

Note that any boolean arguments can be given positively as '1', 't', 'y', 'true', 'yes' or 'on'. Likewise, negative values can be given as '0', 'f', 'n', 'false', 'no' or 'off'. Case is ignored.

## GENERAL COMMANDS
help

Show a quick help on the commands available.

## STATUS COMMANDS
list-modules

Show all currently loaded modules with their arguments.

list-cards

Show all currently registered cards

list-sinks or list-sources

Show all currently registered sinks (resp. sources).

list-clients

Show all currently active clients.

list-sink-inputs or list-source-outputs

Show all currently active inputs to sinks a.k.a. playback streams (resp. outputs of sources a.k.a. recording streams).

stat

Show some simple statistics about the allocated memory blocks and the space used by them.

info or ls or list

A combination of all status commands described above (all three commands are synonyms).

## MODULE MANAGEMENT
load-module name [arguments...]

Load a module specified by its name and arguments. For most modules it is OK to be loaded more than once.

unload-module index|name

Unload a module, specified either by its index in the module list or its name.

describe-module name

Give information about a module specified by its name.

## VOLUME COMMANDS
set-sink-volume|set-source-volume index|name volume

Set the volume of the specified sink (resp. source). You may specify the sink (resp. source) either by its index in the sink/source list or by its name. The volume should be an integer value greater or equal than 0 (muted). Volume 65536 (0x10000) is 'normal' volume a.k.a. 100%. Values greater than this amplify the audio signal (with clipping).

set-sink-mute|set-source-mute index|name boolean

Mute or unmute the specified sink (resp. source). You may specify the sink (resp. source) either by its index or by its name. The mute value is either 0 (not muted) or 1 (muted).

set-sink-input-volume|set-source-output-volume index volume

Set the volume of a sink input (resp. source output) specified by its index. The same volume rules apply as with set-sink-volume.

set-sink-input-mute|set-source-output-mute index boolean

Mute or unmute a sink input (resp. source output) specified by its index. The same mute rules apply as with set-sink-mute.

## CONFIGURATION COMMANDS
set-default-sink|set-default-source index|name

Make a sink (resp. source) the default. You may specify the sink (resp. source) by its index in the sink (resp. source) list or by its name. Use the special name @NONE@ to unset the user defined default sink or source. In this case, pulseaudio will return to the default sink or source selection based on priority. Note that defaults may be overridden by various policy modules or by specific stream configurations.

set-card-profile index|name profile-name

Change the profile of a card.

set-sink-port|set-source-port index|name port-name

Change the profile of a sink (resp. source).

set-port-latency-offset card-index|card-name port-name offset

Change the latency offset of a port belonging to the specified card

suspend-sink|suspend-source name|index true|false

Suspend or resume the specified sink or source (which may be specified either by its name or index), depending whether true (suspend) or false (resume) is passed as last argument. Suspending a sink will pause all playback and suspending a source will pause all capturing. Depending on the module implementing the sink or source this might have the effect that the underlying device is closed, making it available for other applications to use. The exact behaviour depends on the module.

suspend boolean

Suspend all sinks and sources.

## MOVING STREAMS
move-sink-input|move-source-output index sink-index|sink-name

Move sink input (resp. source output) to another sink (resp. source).

## PROPERTY LISTS
update-sink-proplist|update-source-proplist index|name properties

Update the properties of a sink (resp. source) specified by name or index. The property is specified as e.g. device.description="My Preferred Name"

update-sink-input-proplist|update-source-output-proplist index properties

Update the properties of a sink input (resp. source output) specified by index. The properties are specified as above.

## SAMPLE CACHE
list-samples

Lists the contents of the sample cache.

play-sample name sink-index|sink-name

Play a sample cache entry to a sink.

remove-sample name

Remove an entry from the sample cache.

load-sample name filename

Load an audio file to the sample cache.

load-sample-lazy name filename

Create a new entry in the sample cache, but don't load the sample immediately. The sample is loaded only when it is first used. After a certain idle time it is freed again.

load-sample-dir-lazy path

Load all entries in the specified directory into the sample cache as lazy entries. A shell globbing expression (e.g. *.wav) may be appended to the path of the directory to add.

## KILLING CLIENTS/STREAMS
kill-client index

Remove a client forcibly from the server. There is no protection against the client reconnecting immediately.

kill-sink-input|kill-source-output index

Remove a sink input (resp. source output) forcibly from the server. This will not remove the owning client or any other streams opened by the same client from the server.

## LOG COMMANDS
set-log-level numeric-level

Change the log level.

set-log-meta boolean

Show source code location in log messages.

set-log-target target

Change the log target (null, auto, journal, syslog, stderr, file:PATH, newfile:PATH).

set-log-time boolean

Show timestamps in log messages.

set-log-backtrace num-frames

Show backtrace in log messages.

## MISCELLANEOUS COMMANDS
play-file filename sink-index|sink-name

Play an audio file to a sink.

dump

Dump the daemon's current configuration in CLI commands.

dump-volumes

Debug: Shows the current state of all volumes.

shared

Debug: Show shared properties.

send-message recipient message message_parameters

Send a message to the specified recipient object. If applicable an additional string containing message parameters can be specified. A string is returned as a response to the message. For available messages see https://cgit.freedesktop.org/pulseaudio/pulseaudio/tree/doc/messaging_api.txt.

exit

Terminate the daemon. If you want to terminate a CLI connection ("log out") you might want to use ctrl+d

## META COMMANDS
In addition to the commands described above there are a few meta directives supported by the command line interpreter.

.include filename|folder

Executes the commands from the specified script file or in all of the *.pa files within the folder.

.fail and .nofail

Enable (resp. disable) that following failing commands will cancel the execution of the current script file. This is ignored when used on the interactive command line.

.ifexists filename

Execute the subsequent block of commands only if the specified file exists. Typically filename indicates a module. Relative paths are resolved using the module directory as the base. By using an absolute path, the existence of other files can be checked as well.

.else and .endif

A block of commands is delimited by an .else or .endif meta command. Nesting conditional commands is not supported.

## AUTHORS
The PulseAudio Developers <pulseaudio-discuss (at) lists (dot) freedesktop (dot) org>; PulseAudio is available from http://pulseaudio.org/

## SEE ALSO
default.pa(5), pacmd(1), pulseaudio(1)


pulse-daemon.conf

title: pulse-daemon.conf(5)

summary: PulseAudio daemon configuration file

text:
# pulse-daemon.conf(5)

## NAME
pulse-daemon.conf - PulseAudio daemon configuration file

## SYNOPSIS
~/.config/pulse/daemon.conf

~/.config/pulse/daemon.conf.d/*.conf

/etc/pulse/daemon.conf

/etc/pulse/daemon.conf.d/*.conf

## DESCRIPTION
The PulseAudio sound server reads configuration directives from a configuration file on startup. If the per-user file ~/.config/pulse/daemon.conf exists, it is used, otherwise the system configuration file /etc/pulse/daemon.conf is used. In addition to those main files, configuration directives can also be put in files under directories ~/.config/pulse/daemon.conf.d/ and /etc/pulse/daemon.conf.d/. Those files have to have the .conf file name extension, but otherwise the file names can be chosen freely. The files under daemon.conf.d are processed in alphabetical order. In case the same option is set in multiple files, the last file to set an option overrides earlier files. The main daemon.conf file is processed first, so options set in files under daemon.conf.d override the main file.

Please note that the server also reads a configuration script on startup. See default.pa(5).

The configuration file is a simple collection of variable declarations. If the configuration file parser encounters either ; or # it ignores the rest of the line until its end.

For the settings that take a boolean argument the values true, yes, on and 1 are equivalent, resp. false, no, off, 0.

## GENERAL DIRECTIVES
daemonize= Daemonize after startup. Takes a boolean value, defaults to no. The --daemonize command line option takes precedence.

fail= Fail to start up if any of the directives in the configuration script default.pa fail. Takes a boolean argument, defaults to yes. The --fail command line option takes precedence.

allow-module-loading= Allow/disallow module loading after startup. This is a security feature that if disabled makes sure that no further modules may be loaded into the PulseAudio server after startup completed. It is recommended to disable this when system-instance is enabled. Please note that certain features like automatic hot-plug support will not work if this option is enabled. Takes a boolean argument, defaults to yes. The --disallow-module-loading command line option takes precedence.

allow-exit= Allow/disallow exit on user request. Defaults to yes.

resample-method= The resampling algorithm to use. Use one of src-sinc-best-quality, src-sinc-medium-quality, src-sinc-fastest, src-zero-order-hold, src-linear, trivial, speex-float-N, speex-fixed-N, ffmpeg, soxr-mq, soxr-hq, soxr-vhq. See the documentation of libsamplerate and speex for explanations of the different src- and speex- methods, respectively. The method trivial is the most basic algorithm implemented. If you're tight on CPU consider using this. On the other hand it has the worst quality of them all. The Speex resamplers take an integer quality setting in the range 0..10 (bad...good). They exist in two flavours: fixed and float. The former uses fixed point numbers, the latter relies on floating point numbers. On most desktop CPUs the float point resampler is a lot faster, and it also offers slightly better quality. The soxr-family methods are based on libsoxr, a resampler library from the SoX sound processing utility. The mq variant has the best performance of the three. The hq is more expensive and, according to SoX developers, is considered the best choice for audio of up to 16 bits per sample. The vhq variant has more precision than hq and is more suitable for larger samples. The Soxr resamplers generally offer better quality at less CPU compared to other resamplers, such as speex. The downside is that they can add a significant delay to the output (usually up to around 20 ms, in rare cases more). See the output of dump-resample-methods for a complete list of all available resamplers. Defaults to speex-float-1. The --resample-method command line option takes precedence. Note that some modules overwrite or allow overwriting of the resampler to use.

avoid-resampling= If set, try to configure the device to avoid resampling. This only works on devices which support reconfiguring their rate, and when no other streams are already playing or capturing audio. The device will also not be configured to a rate less than the default and alternate sample rates.

enable-remixing= If disabled never upmix or downmix channels to different channel maps. Instead, do a simple name-based matching only. Defaults to yes. There is no known valid use case for setting this option to no, therefore, this option is deprecated and may be removed in a future version of PulseAudio.

remixing-use-all-sink-channels= If enabled, use all sink channels when remixing. Otherwise, remix to the minimal set of sink channels needed to reproduce all of the source channels. (This has no effect on LFE remixing.) Defaults to yes.

enable-lfe-remixing= This is a way to set remixing-produce-lfe and remixing-consume-lfe to the same value at once. This option only exists for backward compatibility and may be removed in a future version of PulseAudio.

remixing-produce-lfe= If enabled, and the sink input does not have the LFE channel, synthesize the output LFE channel as a (lowpass-filtered, if lfe-crossover-freq is not 0) average of all input channels. Also, when lfe-crossover-freq is not 0, filter out low frequencies from other channels while producing a synthetic LFE output. If disabled, the output LFE channel will only get a signal when an input LFE channel is available as well. Defaults to no.

remixing-consume-lfe= If enabled, and the sink does not have an LFE channel, redirect the input LFE channel (if any) to other channels. If disabled, the input LFE channel will remain unused unless the sink has the LFE channel as well. Defaults to no.

lfe-crossover-freq= The crossover frequency (in Hz) for the LFE filter. Set it to 0 to disable the LFE filter. Defaults to 0.

use-pid-file= Create a PID file in the runtime directory ($XDG_RUNTIME_DIR/pulse/pid). If this is enabled you may use commands like --kill or --check. If you are planning to start more than one PulseAudio process per user, you better disable this option since it effectively disables multiple instances. Takes a boolean argument, defaults to yes. The --use-pid-file command line option takes precedence.

cpu-limit= If disabled do not install the CPU load limiter, even on platforms where it is supported. This option is useful when debugging/profiling PulseAudio to disable disturbing SIGXCPU signals. Takes a boolean argument, defaults to no. The --no-cpu-limit command line argument takes precedence.

system-instance= Run the daemon as system-wide instance, requires root privileges. Takes a boolean argument, defaults to no. The --system command line argument takes precedence.

local-server-type= Please don't use this option if you don't have to! This option is currently only useful when you want D-Bus clients to use a remote server. This option may be removed in future versions. If you only want to run PulseAudio in the system mode, use the system-instance option. This option takes one of user, system or none as the argument. This is essentially a duplicate for the system-instance option. The difference is the none option, which is useful when you want to use a remote server with D-Bus clients. If both this and system-instance are defined, this option takes precedence. Defaults to whatever the system-instance is set.

enable-shm= Enable data transfer via POSIX or memfd shared memory. Takes a boolean argument, defaults to yes. The --disable-shm command line argument takes precedence.

enable-memfd=. Enable memfd shared memory. Takes a boolean argument, defaults to yes.

shm-size-bytes= Sets the shared memory segment size for the daemon, in bytes. If left unspecified or is set to 0 it will default to some system-specific default, usually 64 MiB. Please note that usually there is no need to change this value, unless you are running an OS kernel that does not do memory overcommit.

lock-memory= Locks the entire PulseAudio process into memory. While this might increase drop-out safety when used in conjunction with real-time scheduling this takes away a lot of memory from other processes and might hence considerably slow down your system. Defaults to no.

flat-volumes= Enable 'flat' volumes, i.e. where possible let the sink volume equal the maximum of the volumes of the inputs connected to it. Takes a boolean argument, defaults to no.

rescue-streams= Enable rescuing of streams if the used sink or source becomes unavailable. Takes a boolean argument. If set to yes, pulseaudio will try to move the streams from a sink or source that becomes unavailable to the default sink or source. If set to no, streams will be killed if the corresponding sink or source disappears. Defaults to yes.

## SCHEDULING
high-priority= Renice the daemon after startup to become a high-priority process. This a good idea if you experience drop-outs during playback. However, this is a certain security issue, since it works when called SUID root only, or RLIMIT_NICE is used. root is dropped immediately after gaining the nice level on startup, thus it is presumably safe. See pulseaudio(1) for more information. Takes a boolean argument, defaults to yes. The --high-priority command line option takes precedence.

realtime-scheduling= Try to acquire SCHED_FIFO scheduling for the IO threads. The same security concerns as mentioned above apply. However, if PA enters an endless loop, realtime scheduling causes a system lockup. Thus, realtime scheduling should only be enabled on trusted machines for now. Please note that only the IO threads of PulseAudio are made real-time. The controlling thread is left a normally scheduled thread. Thus enabling the high-priority option is orthogonal. See pulseaudio(1) for more information. Takes a boolean argument, defaults to yes. The --realtime command line option takes precedence.

realtime-priority= The realtime priority to acquire, if realtime-scheduling is enabled. Note: JACK uses 10 by default, 9 for clients. Thus it is recommended to choose the PulseAudio real-time priorities lower. Some PulseAudio threads might choose a priority a little lower or higher than the specified value. Defaults to 5.

nice-level= The nice level to acquire for the daemon, if high-priority is enabled. Note: on some distributions X11 uses -10 by default. Defaults to -11.

## IDLE TIMES
exit-idle-time= Terminate the daemon after the last client quit and this time in seconds passed. Use a negative value to disable this feature. Defaults to 20. The --exit-idle-time command line option takes precedence.

When PulseAudio runs in the per-user mode and detects a login session, then any positive value will be reset to 0 so that PulseAudio will terminate immediately on logout. A positive value therefore has effect only in environments where there's no support for login session tracking (or if the user is logged in without a session spawned, a.k.a. lingering). A negative value can still be used to disable any automatic exit.

When PulseAudio runs in the system mode, automatic exit is always disabled, so this option does nothing.

scache-idle-time= Unload autoloaded sample cache entries after being idle for this time in seconds. Defaults to 20. The --scache-idle-time command line option takes precedence.

## PATHS
dl-search-path= The path where to look for dynamic shared objects (DSOs/plugins). You may specify more than one path separated by colons. The default path depends on compile time settings. The --dl-search-path command line option takes precedence.

default-script-file= The default configuration script file to load. Specify an empty string for not loading a default script file. The default behaviour is to load ~/.config/pulse/default.pa, and if that file does not exist fall back to the system wide installed version /etc/pulse/default.pa. If run in system-wide mode the file /etc/pulse/system.pa is used instead. If -n is passed on the command line or default-script-file= is disabled the default configuration script is ignored.

load-default-script-file= Load the default configuration script file as specified in default-script-file=. Defaults to yes.

## LOGGING
log-target= The default log target. Use either stderr, syslog, journal (optional), auto, file:PATH or newfile:PATH. On traditional systems auto is equivalent to syslog. On systemd-enabled systems, auto is equivalent to journal, in case daemonize is enabled, and to stderr otherwise. If set to file:PATH, logging is directed to the file indicated by PATH. newfile:PATH is otherwise the same as file:PATH, but existing files are never overwritten. If the specified file already exists, a suffix is added to the file name to avoid overwriting. Defaults to auto. The --log-target command line option takes precedence.

log-level= Log level, one of debug, info, notice, warning, error. Log messages with a lower log level than specified here are not logged. Defaults to notice. The --log-level command line option takes precedence. The -v command line option might alter this setting.

log-meta= With each logged message log the code location the message was generated from. Defaults to no.

log-time= With each logged message log the relative time since startup. Defaults to no.

log-backtrace= When greater than 0, with each logged message log a code stack trace up the specified number of stack frames. Defaults to 0.

## RESOURCE LIMITS
See getrlimit(2) for more information. Set to -1 if PulseAudio shall not touch the resource limit. Not all resource limits are available on all operating systems.

rlimit-as Defaults to -1.

rlimit-rss Defaults to -1.

rlimit-core Defaults to -1.

rlimit-data Defaults to -1.

rlimit-fsize Defaults to -1.

rlimit-nofile Defaults to 256.

rlimit-stack Defaults to -1.

rlimit-nproc Defaults to -1.

rlimit-locks Defaults to -1.

rlimit-sigpending Defaults to -1.

rlimit-msgqueue Defaults to -1.

rlimit-memlock Defaults to 16 KiB. Please note that the JACK client libraries may require more locked memory.

rlimit-nice Defaults to 31. Please make sure that the default nice level as configured with nice-level fits in this resource limit, if high-priority is enabled.

rlimit-rtprio Defaults to 9. Please make sure that the default real-time priority level as configured with realtime-priority= fits in this resource limit, if realtime-scheduling is enabled. The JACK client libraries require a real-time priority of 9 by default.

rlimit-rttime Defaults to 1000000.

## DEFAULT DEVICE SETTINGS
Most drivers try to open the audio device with these settings and then fall back to lower settings. The default settings are CD quality: 16bit native endian, 2 channels, 44100 Hz sampling.

default-sample-format= The default sampling format. See https://www.freedesktop.org/wiki/Software/PulseAudio/Documentation/User/SupportedAudioFormats/ for possible values.

default-sample-rate= The default sample frequency.

default-sample-channels The default number of channels.

default-channel-map The default channel map.

alternate-sample-rate The alternate sample frequency. Sinks and sources will use either the default-sample-rate value or this alternate value, typically 44.1 or 48kHz. Switching between default and alternate values is enabled only when the sinks/sources are suspended. This option is ignored in passthrough mode where the stream rate will be used. If set to the same value as the default sample rate, this feature is disabled.

## DEFAULT FRAGMENT SETTINGS
Some hardware drivers require the hardware playback buffer to be subdivided into several fragments. It is possible to change these buffer metrics for machines with high scheduling latencies. Not all possible values that may be configured here are available in all hardware. The driver will find the nearest setting supported. Modern drivers that support timer-based scheduling ignore these options.

default-fragments= The default number of fragments. Defaults to 4.

default-fragment-size-msec=The duration of a single fragment. Defaults to 25ms (i.e. the total buffer is thus 100ms long).

## DEFAULT DEFERRED VOLUME SETTINGS
With the flat volume feature enabled, the sink HW volume is set to the same level as the highest volume input stream. Any other streams (with lower volumes) have the appropriate adjustment applied in SW to bring them to the correct overall level. Sadly hardware mixer changes cannot be timed accurately and thus this change of volumes can sometimes cause the resulting output sound to be momentarily too loud or too soft. So to ensure SW and HW volumes are applied concurrently without any glitches, their application needs to be synchronized. The sink implementation needs to support deferred volumes. The following parameters can be used to refine the process.

enable-deferred-volume= Enable deferred volume for the sinks that support it. This feature is enabled by default.

deferred-volume-safety-margin-usec= The amount of time (in usec) by which the HW volume increases are delayed and HW volume decreases are advanced. Defaults to 8000 usec.

deferred-volume-extra-delay-usec= The amount of time (in usec) by which HW volume changes are delayed. Negative values are also allowed. Defaults to 0.

## AUTHORS
The PulseAudio Developers <pulseaudio-discuss (at) lists (dot) freedesktop (dot) org>; PulseAudio is available from http://pulseaudio.org/

## SEE ALSO
pulse-client.conf(5), default.pa(5), pulseaudio(1), pacmd(1)