'\" t .\" Title: ostree .\" Author: Colin Walters .\" Generator: DocBook XSL Stylesheets vsnapshot .\" Date: 03/26/2024 .\" Manual: ostree .\" Source: OSTree .\" Language: English .\" .TH "OSTREE" "1" "" "OSTree" "ostree" .\" ----------------------------------------------------------------- .\" * 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 \- Manage multiple bootable versioned filesystem trees .SH "SYNOPSIS" .HP \w'\fBostree\fR\ 'u \fBostree\fR {COMMAND} [OPTIONS...] .SH "DESCRIPTION" .PP OSTree is a tool for managing multiple bootable versioned filesystem trees, or just "tree" for short\&. In the OSTree model, operating systems no longer live in the physical "/" root directory\&. Instead, they parallel install to the new toplevel /ostree directory\&. Each installed system gets its own /ostree/deploy/\fIstateroot\fR directory\&. (stateroot is the newer term for osname)\&. .PP Unlike rpm or dpkg, OSTree is only aware of complete filesystem trees\&. It has no built\-in knowledge of what components went into creating the filesystem tree\&. .PP It is possible to use OSTree in several modes; the most basic form is to replicate pre\-built trees from a build server\&. Usually, these pre\-built trees are derived from packages\&. You might also be using OSTree underneath a higher level tool which computes filesystem trees locally\&. .PP It must be emphasized that OSTree only supports \fIread\-only\fR trees\&. To change to a different tree (upgrade, downgrade, install software), a new tree is checked out, and a 3\-way merge of configuration is performed\&. The currently running tree is not ever modified; the new tree will become active on a system reboot\&. .PP To see the man page for a command run \fBman ostree \fR\fB\fICOMMAND\fR\fR or \fBman ostree\-admin \fR\fB\fICOMMAND\fR\fR .SH "OPTIONS" .PP The following options are understood: .PP \fB\-\-repo\fR .RS 4 For most commands, a repository is required\&. If unspecified, the current directory is used if it appears to be an OSTree repository\&. If it isn\*(Aqt, either the \fBOSTREE_REPO\fR environment variable is used, or the system repository located at /sysroot/ostree/repo\&. .RE .PP \fB\-v, \-\-verbose\fR .RS 4 Produce debug level output\&. .RE .PP \fB\-\-version\fR .RS 4 Print version information, including the features enabled at compile time, and exit\&. .RE .SH "COMMANDS" .PP System administrators will primarily interact with OSTree via the subcommand \fBostree admin\fR\&. .PP \fBostree-admin-cleanup\fR(1) .RS 4 Delete untagged deployments and repository objects\&. .RE .PP \fBostree-admin-config-diff\fR(1) .RS 4 See changes to /etc as compared to the current default (from /usr/etc)\&. .RE .PP \fBostree-admin-deploy\fR(1) .RS 4 Takes a particular commit or revision, and sets it up for the next boot\&. .RE .PP \fBostree-admin-init-fs\fR(1) .RS 4 Initialize a root filesystem in a specified path\&. .RE .PP \fBostree-admin-instutil\fR(1) .RS 4 Utility functions intended primarily for operating system installation programs .RE .PP \fBostree-admin-os-init\fR(1) .RS 4 Initialize the deployment location for an operating system with a specified name\&. .RE .PP \fBostree-admin-status\fR(1) .RS 4 Show and list the deployments\&. .RE .PP \fBostree-admin-switch\fR(1) .RS 4 Choose a different ref to track from the same remote as the current tree\&. .RE .PP \fBostree-admin-undeploy\fR(1) .RS 4 Remove the previously \fIINDEX\fR deployed tree from the bootloader configuration\&. .RE .PP \fBostree-admin-upgrade\fR(1) .RS 4 Download the latest version for the current ref, and deploy it\&. .RE .PP Both administrators and operating system builders may interact with OSTree via the regular filesystem manipulation commands\&. .PP \fBostree-cat\fR(1) .RS 4 Concatenate contents of files .RE .PP \fBostree-checkout\fR(1) .RS 4 Check out a commit into a filesystem tree\&. .RE .PP \fBostree-checksum\fR(1) .RS 4 Gives checksum of any file\&. .RE .PP \fBostree-commit\fR(1) .RS 4 Given one or more trees, create a new commit using those contents\&. .RE .PP \fBostree-config\fR(1) .RS 4 Change settings\&. .RE .PP \fBostree-create-usb\fR(1) .RS 4 Put the given refs on an external drive for P2P distribution\&. .RE .PP \fBostree-diff\fR(1) .RS 4 Concisely list differences between the given refs\&. .RE .PP \fBostree-find-remotes\fR(1) .RS 4 Find remotes to serve the given refs\&. .RE .PP \fBostree-fsck\fR(1) .RS 4 Check a repository for consistency\&. .RE .PP \fBostree-init\fR(1) .RS 4 Initialize a new repository\&. .RE .PP \fBostree-log\fR(1) .RS 4 Show revision log\&. .RE .PP \fBostree-ls\fR(1) .RS 4 List the contents of a given commit\&. .RE .PP \fBostree-prune\fR(1) .RS 4 Search for unreachable objects\&. .RE .PP \fBostree-pull-local\fR(1) .RS 4 Copy data from source\-repo\&. .RE .PP \fBostree-pull\fR(1) .RS 4 Download data from remote repo\&. If you have libsoup\&. .RE .PP \fBostree-refs\fR(1) .RS 4 List refs\&. .RE .PP \fBostree-remote\fR(1) .RS 4 Manipulate remote archive configuration\&. .RE .PP \fBostree-reset\fR(1) .RS 4 Reset a ref to a previous commit\&. .RE .PP \fBostree-rev-parse\fR(1) .RS 4 Show the SHA256 corresponding to a given rev\&. .RE .PP \fBostree-show\fR(1) .RS 4 Given an OSTree SHA256 checksum, display its contents\&. .RE .PP \fBostree-static-delta\fR(1) .RS 4 Manage static delta files\&. .RE .PP \fBostree-summary\fR(1) .RS 4 Regenerate the repository summary metadata\&. .RE .SH "EXAMPLES" .PP For specific examples, please see the man page regarding the specific ostree command\&. For example: .PP \fBman ostree init\fR or \fBman ostree\-admin status\fR .SH "GPG VERIFICATION" .PP OSTree supports signing commits with GPG\&. Operations on the system repository by default use keyring files in /usr/share/ostree/trusted\&.gpg\&.d\&. Any public key in a keyring file in that directory will be trusted by the client\&. No private keys should be present in this directory\&. .PP In addition to the system repository, OSTree supports two other paths\&. First, there is a gpgkeypath option for remotes, which must point to the filename of an ASCII\-armored GPG key, or a directory containing ASCII\-armored GPG keys to import\&. Multiple file and directory paths to import from can be specified, as a comma\-separated list of paths\&. This option may be specified by using \fB\-\-set\fR in \fBostree remote add\fR\&. .PP Second, there is support for a per\-remote \fIremotename\fR\&.trustedkeys\&.gpg file stored in the toplevel of the repository (alongside objects/ and such)\&. This is particularly useful when downloading content that may not be fully trusted (e\&.g\&. you want to inspect it but not deploy it as an OS), or use it for containers\&. This file is written via \fBostree remote add \-\-gpg\-import\fR\&. .SH "TERMINOLOGY" .PP The following terms are commonly used throughout the man pages\&. Terms in upper case letters are literals used in command line arguments\&. .PP BRANCH .RS 4 Branch name\&. Part of a REF\&. .RE .PP CHECKSUM .RS 4 A SHA256 hash of a object stored in the OSTree repository\&. This can be a content, a dirtree, a dirmeta or a commit object\&. If the SHA256 hash of a commit object is meant, the term COMMIT is used\&. .RE .PP COMMIT .RS 4 A SHA256 hash of a commit object\&. .RE .PP REF .RS 4 A reference to a particular commit\&. References are text files stored in refs/ that name (refer to) a particular commit\&. A reference can only be the branch name part, in which case a local reference is used (e\&.g\&. mybranch/stable)\&. If a remote branch is referred to, the remote name followed by a colon and the branch name needs to be used (e\&.g\&. myremote:mybranch/stable)\&. .RE .PP REV, REFSPEC .RS 4 A specific revision, a commit\&. This can be anything which can be resolved to a commit, e\&.g\&. a REF or a COMMIT\&. .RE .PP SHA256 .RS 4 A cryptographic hash function used to store objects in the OSTree repository\&. The hashes have a length of 256 bites and are typically shown and passed to ostree in its 64 ASCII character long hexadecimal representation (e\&.g\&. 0fc70ed33cfd7d26fe99ae29afb7682ddd0e2157a4898bd8cfcdc8a03565b870)\&. .RE .SH "SEE ALSO" .PP \fBostree.repo\fR(5)