'\" t
.\"     Title: ostree.repo-config
.\"    Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
.\" Generator: DocBook XSL Stylesheets v1.79.2 <http://docbook.sf.net/>
.\"      Date: 10/30/2026
.\"    Manual: ostree.repo-config
.\"    Source: OSTree
.\"  Language: English
.\"
.TH "OSTREE\&.REPO\-CONFI" "5" "" "OSTree" "ostree.repo-config"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------


  

  

  .SH "NAME"
ostree.repo-config \- OSTree repository configuration


  .SH "DESCRIPTION"

    

    .PP
The
config
file in an OSTree repository is a "keyfile" in the
\m[blue]\fBXDG Desktop Entry Specification\fR\m[]\&\s-2\u[1]\d\s+2
format\&. It has several global flags, as well as zero or more remote entries which describe how to access remote repositories\&.

    
    .PP
See
\fBostree.repo\fR(5)
for more information about OSTree repositories\&.

  

  .SH "[CORE] SECTION OPTIONS"

    

    .PP
Repository\-global options\&. The following entries are defined:


    

      .PP
\fImode\fR
.RS 4

        
        One of
bare,
bare\-user,
bare\-user\-only, or
archive\-z2
(note that
archive
is used everywhere else\&.)

      .RE

      .PP
\fIrepo_version\fR
.RS 4

        
        Currently, this must be set to
1\&.

      .RE

      .PP
\fIauto\-update\-summary\fR
.RS 4

        
        Boolean value controlling whether or not to automatically update the summary file after any ref is added, removed, or updated\&. Other modifications which may render a summary file stale (like static deltas, or collection IDs) do not currently trigger an auto\-update\&.

      .RE

      .PP
\fIcommit\-update\-summary\fR
.RS 4

        
        This option is deprecated\&. Use
auto\-update\-summary
instead, for which this option is now an alias\&.

      .RE

      .PP
\fIfsync\fR
.RS 4

        
        Boolean value controlling whether or not to ensure files are on stable storage when performing operations such as commits, pulls, and checkouts\&. Defaults to
true\&.
.sp

        If you disable fsync, OSTree will no longer be robust against kernel crashes or power loss\&.
.sp

        You might choose to disable this for local development repositories, under the assumption they can be recreated from source\&. Similarly, you could disable for a mirror where you could re\-pull\&.
.sp

        For the system repository, you might choose to disable fsync if you have uninterruptable power supplies and a well tested kernel\&.

        
      .RE

      .PP
\fIper\-object\-fsync\fR
.RS 4

        
        By default, OSTree will batch fsync() after writing everything; however, this can cause latency spikes for other processes which are also invoking fsync()\&. Turn on this boolean to reduce potential latency spikes, at the cost of slowing down OSTree updates\&. You most likely want this on by default for "background" OS updates\&.

        
      .RE

      .PP
\fImin\-free\-space\-percent\fR
.RS 4

        
        
          Integer percentage value (0\-99) that specifies a minimum percentage of total space (in blocks) in the underlying filesystem to keep free\&. The default value is 3, which is used when neither this option nor
\fImin\-free\-space\-size\fR
are set (together with a default
\fImin\-free\-space\-size\fR
of
1GB; the smaller of the two is enforced)\&.
.sp

          If
\fImin\-free\-space\-size\fR
is set to a non\-zero value, the smaller of the two limits is used\&. Note that,
\fImin\-free\-space\-percent\fR
is not enforced on metadata objects\&. It is assumed that metadata objects are relatively small in size compared to content objects and thus kept outside the scope of this option\&.

        
      .RE

     .PP
\fImin\-free\-space\-size\fR
.RS 4

        
        
          Value (in power\-of\-2 MB, GB or TB) that specifies a minimum space in the underlying filesystem to keep free\&. Examples of acceptable values:
500MB
(524\ \&288\ \&000 bytes),
1GB
(1\ \&073\ \&741\ \&824 bytes),
1TB
(1\ \&099\ \&511\ \&627\ \&776 bytes)\&.
.sp

          If this option is set to a non\-zero value, and
\fImin\-free\-space\-percent\fR
is also set, the smaller of the two limits is used\&. When neither option is set, the default is
1GB
(capped at 3% of total filesystem size)\&. Note that,
\fImin\-free\-space\-size\fR
is not enforced on metadata objects\&. It is assumed that metadata objects are relatively small in size compared to content objects and thus kept outside the scope of this option\&.

        
      .RE

      .PP
\fIadd\-remotes\-config\-dir\fR
.RS 4

        
        
          Boolean value controlling whether new remotes will be added in the remotes configuration directory\&. Defaults to
true
for system ostree repositories\&. When this is
false, remotes will be added in the repository\*(Aqs
config
file\&.
.sp

          This only applies to repositories that use a remotes configuration directory such as system ostree repositories, which use
/etc/ostree/remotes\&.d\&. Non\-system repositories do not use a remotes configuration directory unless one is specified when the repository is opened\&.

        
      .RE

      .PP
\fIpayload\-link\-threshold\fR
.RS 4

        
        An integer value that specifies a minimum file size for creating a payload link\&. By default it is disabled\&.

      .RE

      .PP
\fIcollection\-id\fR
.RS 4

        
        A reverse DNS domain name under your control, which enables peer to peer distribution of refs in this repository\&. See the
\-\-collection\-id
section in
\fBostree-init\fR(1)

      .RE

      .PP
\fIlocking\fR
.RS 4

        
        Boolean value controlling whether or not OSTree does repository locking internally\&. This uses file locks and is hence for multiple process exclusion (e\&.g\&. Flatpak and OSTree writing to the same repository separately)\&. This is enabled by default since 2018\&.5\&.

      .RE

      .PP
\fIlock\-timeout\-secs\fR
.RS 4

        
        Integer value controlling the number of seconds to block while attempting to acquire a lock (see above)\&. A value of \-1 means block indefinitely\&. The default value is 300\&. This timeout is now regarded as a mistake; because it\*(Aqs likely to cause flakes\&. It\*(Aqs recommended to set it to \-1, and have timeouts at a higher application level if desired\&.

      .RE

      .PP
\fIdefault\-repo\-finders\fR
.RS 4

        
        Semicolon separated default list of finders (sources for refs) to use when pulling\&. This can be used to disable pulling from mounted filesystems, peers on the local network, or the Internet\&. However note that it only applies when a set of finders isn\*(Aqt explicitly specified, either by a consumer of libostree API or on the command line\&. Possible values:
config,
lan, and
mount
(or any combination thereof)\&. If unset, this defaults to
config;mount;
(since the LAN finder is costly)\&.

      .RE

      .PP
\fIno\-deltas\-in\-summary\fR
.RS 4

        
        Boolean value controlling whether OSTree should skip putting an index of available deltas in the summary file\&. Defaults to false\&.
.sp

        Since 2020\&.7 OSTree can use delta indexes outside the summary file, making the summary file smaller (especially for larger repositories)\&. However by default we still create the index in the summary file to make older clients work\&. If you know all clients will be 2020\&.7 later you can enable this to save network bandwidth\&.

      .RE

      .PP
\fIsign\-verify\-deltas\fR
.RS 4

        
        A boolean value, defaults to false\&. When true, applying a
\fIsigned\fR
static delta with
\fBostree static\-delta apply\-offline\fR
requires a key to be supplied, and fails with
Key is mandatory to check delta signature
when none is\&.
.sp

        This option cannot require a delta to be signed\&. It is consulted only after a delta has been found to carry a signature, so an unsigned delta is applied whatever this is set to\&. It also has no effect on
\fBostree pull\fR, which cannot consume signed deltas at all; see
\fBostree-static-delta\fR(1)\&.

      .RE
    
  

  .SH "[REMOTE "NAME"] SECTION OPTIONS"

    
    
    .PP
Describes a remote repository location\&.


    

      .PP
\fIurl\fR
.RS 4

        
        Must be present; declares URL for accessing metadata and content for remote\&. See also
contenturl\&. The supported schemes are documented below\&.

      .RE

      .PP
\fIcontenturl\fR
.RS 4

        
        Declares URL for accessing content (filez, static delta parts)\&. When specified,
url
is used just for metadata: summary, static delta "superblocks"\&.

      .RE

      .PP
\fIbranches\fR
.RS 4

        
        A list of strings\&. Represents the default configured branches to fetch from the remote when no specific branches are requested during a pull operation\&.

      .RE

      .PP
\fIproxy\fR
.RS 4

        
        A string value, if given should be a URL for a HTTP proxy to use for access to this repository\&.

      .RE

      .PP
\fIgpg\-verify\fR
.RS 4

        
        A boolean value, defaults to true\&. Controls whether or not OSTree will require commits to be signed by a known GPG key\&. For more information, see the
\fBostree\fR(1)
manual under GPG\&.

      .RE

      .PP
\fIgpg\-verify\-summary\fR
.RS 4

        
        A boolean value, defaults to false\&. Controls whether or not OSTree will check if the summary is signed by a known GPG key\&. For more information, see the
\fBostree\fR(1)
manual under GPG\&.

      .RE

      .PP
\fIsign\-verify\fR
.RS 4

        
        Controls whether OSTree will require commits to be signed by a known key using one of the non\-GPG signature engines (currently
ed25519)\&. If unset, empty, or set to a boolean\-false value (false
or
0), no such verification is performed\&.
.sp

        A boolean\-true value enables every compiled\-in signature engine\&. Keys are optional in this case: an engine with no
\fIverification\-<engine>\fR
option set for the remote is still enabled, and falls back to the system\-wide key storage\&. Any other value is read as a semicolon\-delimited list of engine names\&. Keys for each named engine then become mandatory rather than optional, and a commit is accepted if any one of the named engines finds a valid signature for it\&.
.sp

        Public keys are supplied by the companion options
\fIverification\-<engine>\-key\fR, holding an inline key, and
\fIverification\-<engine>\-file\fR, holding a path to a file of keys, for example
\fIverification\-ed25519\-file\fR\&.
\fBostree remote add \-\-sign\-verify=ed25519=file:/path/to/key\fR
writes this option and the matching companion together\&.
.sp

        This setting is independent of
\fIgpg\-verify\fR, which defaults to true\&. Enabling only
\fIsign\-verify\fR
therefore leaves GPG verification enabled as well, and a pull against a remote with no GPG signatures fails with
GPG verification enabled, but no signatures found
until
\fIgpg\-verify\fR
is also set to false\&.

        
      .RE

      .PP
\fIsign\-verify\-summary\fR
.RS 4

        
        As
\fIsign\-verify\fR, but controls whether the summary must carry a valid signature\&. If unset or empty the summary is not verified\&.

      .RE

      .PP
\fItls\-permissive\fR
.RS 4

        
        A boolean value, defaults to false\&. By default, server TLS certificates will be checked against the system certificate store\&. If this variable is set, any certificate will be accepted\&.

      .RE

      .PP
\fItls\-client\-cert\-path\fR
.RS 4

        
        Path to file for client\-side certificate, to present when making requests to this repository\&.

      .RE

      .PP
\fItls\-client\-key\-path\fR
.RS 4

        
        Path to file containing client\-side certificate key, to present when making requests to this repository\&.

      .RE

      .PP
\fItls\-ca\-path\fR
.RS 4

        
        Path to file containing trusted anchors instead of the system CA database\&.

      .RE

      .PP
\fIhttp2\fR
.RS 4

        
        A boolean value, defaults to true\&. By default, libostree will use HTTP2; setting this to
false
will disable it\&. May be useful to work around broken servers\&.

      .RE

      .PP
\fIunconfigured\-state\fR
.RS 4

        
        If set, pulls from this remote will fail with the configured text\&. This is intended for OS vendors which have a subscription process to access content\&.

      .RE

      .PP
\fIcustom\-backend\fR
.RS 4

        
        If set, pulls from this remote via libostree will fail with an error that mentions the value\&. It is recommended to make this a software identifier token (e\&.g\&. "examplecorp\-fetcher"), not freeform text ("ExampleCorp Fetcher")\&. This is intended to be used by higher level software that wants to fetch ostree commits via some other mechanism, while still reusing the core libostree infrastructure around e\&.g\&. signatures\&.

      .RE

    

  

  .SH "[SYSROOT] SECTION OPTIONS"

    

    .PP
Options for the sysroot, which contains the OSTree repository, deployments, and stateroots\&. The following entries are defined:


    


      .PP
\fIreadonly\fR
.RS 4

        
        A boolean value\&. If this is set to
true, then the
/sysroot
mount point is mounted read\-only\&. This is configured a legacy repository configuration and the equivalent option in
ostree/prepare\-root\&.conf
should be used instead \- see
\fBostree-prepare-root\fR(1)\&.

      .RE

      .PP
\fIbootloader\fR
.RS 4

        
        Configure the bootloader that OSTree uses when deploying the sysroot\&. This may take the values
bootloader=none,
bootloader=auto,
bootloader=grub2,
bootloader=syslinux,
bootloader=uboot
or
bootloader=zipl\&. Default is
auto\&.
.sp

        If
none, then OSTree will generate only BLS (Boot Loader Specification) fragments in
sysroot/boot/loader/entries/
for the deployment\&.
.sp

        If
auto, then in addition to generating BLS fragments, OSTree will dynamically check for the existence of grub2, uboot, and syslinux bootloaders\&. If one of the bootloaders is found, then OSTree will generate a config for the bootloader found\&. For example,
grub2\-mkconfig
is run for the grub2 case\&.
.sp

        A specific bootloader type may also be explicitly requested by choosing
grub2,
syslinux,
uboot
or
zipl\&.

        
      .RE

      .PP
\fIboot\-counting\-tries\fR
.RS 4

        
        Integer value controlling the number of maximum boot attempts\&. The boot counting data is stored in the name of the boot loader entry\&. A boot loader entry file name may contain a plus (+) followed by a number\&. This may optionally be followed by a minus (\-) followed by a second number\&. The dot (\&.) and file name suffix (conf or efi) must immediately follow\&. More details in the
\m[blue]\fBThe Boot Loader Specification\fR\m[]\&\s-2\u[2]\d\s+2

      .RE

      .PP
\fIbls\-append\-except\-default\fR
.RS 4

        
        A semicolon separated string list of key\-value pairs\&. For example:
bls\-append\-except\-default=key1=value1;key2=value2\&. These key\-value pairs will be injected into the generated BLS fragments of the non\-default deployments\&. In other words, the BLS fragment of the default deployment will be unaffected by
bls\-append\-except\-default\&.

        
      .RE

      .PP
\fIbootprefix\fR
.RS 4

        
        A boolean value; defaults to false\&. If set to true, the bootloader entries generated will include
/boot
as a prefix\&. This will likely be turned on by default in the future\&.

        
      .RE

    
  

  .SH "[EX\-INTEGRITY] SECTION OPTIONS"

    

    .PP
The "ex\-" prefix here signifies experimental options\&. The
ex\-integrity
section contains options related to system integrity\&. Information about experimental options is canonically found in upstream tracking issues\&.

  

  .SH "/ETC/OSTREE/REMOTES\&.D"

    

    .PP
In addition to the
/ostree/repo/config
file, remotes may also be specified in
/etc/ostree/remotes\&.d\&. The remote configuration file must end in
\&.conf; files whose name does not end in
\&.conf
will be ignored\&.

  

  .SH "REPOSITORY URL/CONTENTURL"

    
    .PP
Originally, OSTree had just a
url
option for remotes\&. Since then, the
contenturl
option was introduced\&. Both of these support
file,
http, and
https
schemes\&.

    .PP
Additionally, both of these can be prefixed with the string
mirrorlist=, which instructs the client that the target url is a "mirrorlist" format, which is a plain text file of newline\-separated URLs\&. Earlier URLs will be given precedence\&.

    .PP
Note that currently, the
tls\-ca\-path
and
tls\-client\-cert\-path
options apply to every HTTP request, even when
contenturl
and/or
mirrorlist
are in use\&. This may change in the future to only apply to metadata (i\&.e\&.
url, not
contenturl) fetches\&.

  

  .SH "PER\-REMOTE GPG KEYRINGS AND VERIFICATION"

    
    .PP
OSTree supports a per\-remote GPG keyring, as well as a
gpgkeypath
option\&. For more information see
\fBostree\fR(1)\&. in the section
GPG verification\&.

  

  .SH "PER\-REMOTE HTTP COOKIES"

    
    .PP
Some content providers may want to control access to remote repositories via HTTP cookies\&. The
\fBostree remote add\-cookie\fR
and
\fBostree remote delete\-cookie\fR
commands will update a per\-remote lookaside cookie jar, named
$remotename\&.cookies\&.txt\&.

  
  
  .SH "SEE ALSO"

    
    .PP
\fBostree\fR(1),
\fBostree.repo\fR(5)

  
.SH "NOTES"
.IP " 1." 4
XDG Desktop Entry Specification
.RS 4
\%http://standards.freedesktop.org/desktop-entry-spec/latest/
.RE
.IP " 2." 4
The Boot Loader Specification
.RS 4
\%https://uapi-group.org/specifications/specs/boot_loader_specification/#boot-counting
.RE