'\" t
.\"     Title: ostree.repo-config
.\"    Author: Colin Walters <walters@verbum.org>
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 03/26/2024
.\"    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 enforced when neither this option nor
\fImin\-free\-space\-size\fR
are set\&.
.sp
If
\fImin\-free\-space\-size\fR
is set to a non\-zero value,
\fImin\-free\-space\-percent\fR
is ignored\&. 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, this option takes priority\&. 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
.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
\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
\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