2016-01-27 20:51:07 +03:00
# Makefile for man/
#
# Copyright (C) 2016 Colin Walters <walters@verbum.org>
#
2018-01-30 22:26:26 +03:00
# SPDX-License-Identifier: LGPL-2.0+
#
2016-01-27 20:51:07 +03:00
# This library is free software; you can redistribute it and/or
# modify it under the terms of the GNU Lesser General Public
# License as published by the Free Software Foundation; either
# version 2 of the License, or (at your option) any later version.
#
# This library 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
# Lesser General Public License for more details.
#
# You should have received a copy of the GNU Lesser General Public
2021-12-07 04:20:55 +03:00
# License along with this library. If not, see <https://www.gnu.org/licenses/>.
2016-01-27 20:51:07 +03:00
2023-05-01 21:21:19 +03:00
# This needs to be outside the conditional to avoid a warning
.PHONY: manhtml
2016-01-28 23:34:38 +03:00
if ENABLE_MAN
2022-04-09 01:51:59 +03:00
# If you add a new man page here, add a reference to it in index.xml and
# ostree.xml.
admin: Add an `unlock` command, and libostree API
I'm trying to improve the developer experience on OSTree-managed
systems, and I had an epiphany the other day - there's no reason we
have to be absolutely against mutating the current rootfs live. The
key should be making it easy to rollback/reset to a known good state.
I see this command as useful for two related but distinct workflows:
- `ostree admin unlock` will assume you're doing "development". The
semantics hare are that we mount an overlayfs on `/usr`, but the
overlay data is in `/var/tmp`, and is thus discarded on reboot.
- `ostree admin unlock --hotfix` first clones your current deployment,
then creates an overlayfs over `/usr` persistent
to this deployment. Persistent in that now the initramfs switchroot
tool knows how to mount it as well. In this model, if you want
to discard the hotfix, at the moment you roll back/reboot into
the clone.
Note originally, I tried using `rofiles-fuse` over `/usr` for this,
but then everything immediately explodes because the default (at least
CentOS 7) SELinux policy denies tons of things (including `sshd_t`
access to `fusefs_t`). Sigh.
So the switch to `overlayfs` came after experimentation. It still
seems to have some issues...specifically `unix_chkpwd` is broken,
possibly because it's setuid? Basically I can't ssh in anymore.
But I *can* `rpm -Uvh strace.rpm` which is handy.
NOTE: I haven't tested the hotfix path fully yet, specifically
the initramfs bits.
2016-03-18 22:32:58 +03:00
man1_files = ostree.1 ostree-admin-cleanup.1 \
ostree-admin-config-diff.1 ostree-admin-deploy.1 \
2023-08-17 23:46:02 +03:00
ostree-admin-init-fs.1 ostree-admin-instutil.1 ostree-admin-stateroot-init.1 ostree-admin-os-init.1 \
admin: Add an `unlock` command, and libostree API
I'm trying to improve the developer experience on OSTree-managed
systems, and I had an epiphany the other day - there's no reason we
have to be absolutely against mutating the current rootfs live. The
key should be making it easy to rollback/reset to a known good state.
I see this command as useful for two related but distinct workflows:
- `ostree admin unlock` will assume you're doing "development". The
semantics hare are that we mount an overlayfs on `/usr`, but the
overlay data is in `/var/tmp`, and is thus discarded on reboot.
- `ostree admin unlock --hotfix` first clones your current deployment,
then creates an overlayfs over `/usr` persistent
to this deployment. Persistent in that now the initramfs switchroot
tool knows how to mount it as well. In this model, if you want
to discard the hotfix, at the moment you roll back/reboot into
the clone.
Note originally, I tried using `rofiles-fuse` over `/usr` for this,
but then everything immediately explodes because the default (at least
CentOS 7) SELinux policy denies tons of things (including `sshd_t`
access to `fusefs_t`). Sigh.
So the switch to `overlayfs` came after experimentation. It still
seems to have some issues...specifically `unix_chkpwd` is broken,
possibly because it's setuid? Basically I can't ssh in anymore.
But I *can* `rpm -Uvh strace.rpm` which is handy.
NOTE: I haven't tested the hotfix path fully yet, specifically
the initramfs bits.
2016-03-18 22:32:58 +03:00
ostree-admin-status.1 ostree-admin-set-origin.1 ostree-admin-switch.1 \
ostree-admin-undeploy.1 ostree-admin-upgrade.1 ostree-admin-unlock.1 \
2023-11-13 19:33:57 +03:00
ostree-admin-pin.1 ostree-admin-post-copy.1 ostree-admin-set-default.1 \
2023-11-09 01:19:19 +03:00
ostree-admin-lock-finalization.1 \
admin: Add an `unlock` command, and libostree API
I'm trying to improve the developer experience on OSTree-managed
systems, and I had an epiphany the other day - there's no reason we
have to be absolutely against mutating the current rootfs live. The
key should be making it easy to rollback/reset to a known good state.
I see this command as useful for two related but distinct workflows:
- `ostree admin unlock` will assume you're doing "development". The
semantics hare are that we mount an overlayfs on `/usr`, but the
overlay data is in `/var/tmp`, and is thus discarded on reboot.
- `ostree admin unlock --hotfix` first clones your current deployment,
then creates an overlayfs over `/usr` persistent
to this deployment. Persistent in that now the initramfs switchroot
tool knows how to mount it as well. In this model, if you want
to discard the hotfix, at the moment you roll back/reboot into
the clone.
Note originally, I tried using `rofiles-fuse` over `/usr` for this,
but then everything immediately explodes because the default (at least
CentOS 7) SELinux policy denies tons of things (including `sshd_t`
access to `fusefs_t`). Sigh.
So the switch to `overlayfs` came after experimentation. It still
seems to have some issues...specifically `unix_chkpwd` is broken,
possibly because it's setuid? Basically I can't ssh in anymore.
But I *can* `rpm -Uvh strace.rpm` which is handy.
NOTE: I haven't tested the hotfix path fully yet, specifically
the initramfs bits.
2016-03-18 22:32:58 +03:00
ostree-admin.1 ostree-cat.1 ostree-checkout.1 ostree-checksum.1 \
2019-05-19 16:47:45 +03:00
ostree-commit.1 ostree-create-usb.1 ostree-export.1 \
Make P2P API public (no longer experimental)
Currently the API that allows P2P operations (e.g. pulling an ostree ref
from a LAN or USB source) is hidden behind the configure flag
--enable-experimental-api. This commit makes the API public and makes
that flag essentially a no-op (leaving it in place in case we want to
use it again in the future). The P2P API has been tested over the last
several months and proven to work.
This means that since we're no longer using the "experimental" feature
flag, P2P builds of Flatpak will fail when using versions of OSTree from
this commit onwards, until Flatpak is patched in the near future. If you
want to build Flatpak < 0.11.8 with P2P enabled and link against OSTree
2018.6, you'll have to patch Flatpak. However, since Flatpak won't yet
have a hard dependency on OSTree 2018.6, it needs a new way to determine
if the P2P API in OSTree is available, so this commit adds a "p2p"
feature flag. This way the feature set is more semantically correct than
if we had continued to use the "experimental" feature flag.
In addition to making the P2P API public, this commit makes the P2P unit
tests run by default, removes the f27-experimental CI instance that's no
longer needed, changes a few man pages to reflect the changes, and
updates the bash completion script to accept the new commands and
options.
Closes: #1596
Approved by: cgwalters
2018-05-23 01:55:14 +03:00
ostree-config.1 ostree-diff.1 ostree-find-remotes.1 ostree-fsck.1 \
ostree-init.1 ostree-log.1 ostree-ls.1 ostree-prune.1 ostree-pull-local.1 \
ostree-pull.1 ostree-refs.1 ostree-remote.1 ostree-reset.1 \
2019-11-01 02:44:25 +03:00
ostree-rev-parse.1 ostree-show.1 ostree-sign.1 ostree-summary.1 \
2023-07-14 00:20:32 +03:00
ostree-static-delta.1 ostree-prepare-root.1
2016-01-27 20:51:07 +03:00
2016-02-10 14:42:54 +03:00
if BUILDOPT_FUSE
man1_files += rofiles-fuse.1
endif
2019-05-19 16:47:45 +03:00
if USE_GPGME
man1_files += ostree-gpg-sign.1
endif
2016-01-27 20:51:07 +03:00
man5_files = ostree.repo.5 ostree.repo-config.5
Add concept of state overlays
In the OSTree model, executables go in `/usr`, state in `/var` and
configuration in `/etc`. Software that lives in `/opt` however messes
this up because it often mixes code *and* state, making it harder to
manage.
More generally, it's sometimes useful to have the OSTree commit contain
code under a certain path, but still allow that path to be writable by
software and the sysadmin at runtime (`/usr/local` is another instance).
Add the concept of state overlays. A state overlay is an overlayfs
mount whose upper directory, which contains unmanaged state, is carried
forward on top of a lower directory, containing OSTree-managed files.
In the example of `/usr/local`, OSTree commits can ship content there,
all while allowing users to e.g. add scripts in `/usr/local/bin` when
booted into that commit.
Some reconciliation logic is executed whenever the base is updated so
that newer files in the base are never shadowed by a copied up version
in the upper directory. This matches RPM semantics when upgrading
packages whose files may have been modified.
For ease of integration, this is exposed as a systemd template unit which
any downstream distro/user can enable. The instance name is the mountpath
in escaped systemd path notation (e.g.
`ostree-state-overlay@usr-local.service`).
See discussions in https://github.com/ostreedev/ostree/issues/3113 for
more details.
2023-12-15 00:46:14 +03:00
man8_files = ostree-state-overlay@.service.8
2016-01-27 20:51:07 +03:00
man1_MANS = $(addprefix man/,$(man1_files))
man5_MANS = $(addprefix man/,$(man5_files))
Add concept of state overlays
In the OSTree model, executables go in `/usr`, state in `/var` and
configuration in `/etc`. Software that lives in `/opt` however messes
this up because it often mixes code *and* state, making it harder to
manage.
More generally, it's sometimes useful to have the OSTree commit contain
code under a certain path, but still allow that path to be writable by
software and the sysadmin at runtime (`/usr/local` is another instance).
Add the concept of state overlays. A state overlay is an overlayfs
mount whose upper directory, which contains unmanaged state, is carried
forward on top of a lower directory, containing OSTree-managed files.
In the example of `/usr/local`, OSTree commits can ship content there,
all while allowing users to e.g. add scripts in `/usr/local/bin` when
booted into that commit.
Some reconciliation logic is executed whenever the base is updated so
that newer files in the base are never shadowed by a copied up version
in the upper directory. This matches RPM semantics when upgrading
packages whose files may have been modified.
For ease of integration, this is exposed as a systemd template unit which
any downstream distro/user can enable. The instance name is the mountpath
in escaped systemd path notation (e.g.
`ostree-state-overlay@usr-local.service`).
See discussions in https://github.com/ostreedev/ostree/issues/3113 for
more details.
2023-12-15 00:46:14 +03:00
man8_MANS = $(addprefix man/,$(man8_files))
2016-01-27 20:51:07 +03:00
2021-05-21 20:57:54 +03:00
manhtml_files = \
2022-04-09 01:51:59 +03:00
man/html/index.html \
2021-05-21 20:57:54 +03:00
$(addprefix man/html/,$(man1_files:.1=.html)) \
$(addprefix man/html/,$(man5_files:.5=.html)) \
Add concept of state overlays
In the OSTree model, executables go in `/usr`, state in `/var` and
configuration in `/etc`. Software that lives in `/opt` however messes
this up because it often mixes code *and* state, making it harder to
manage.
More generally, it's sometimes useful to have the OSTree commit contain
code under a certain path, but still allow that path to be writable by
software and the sysadmin at runtime (`/usr/local` is another instance).
Add the concept of state overlays. A state overlay is an overlayfs
mount whose upper directory, which contains unmanaged state, is carried
forward on top of a lower directory, containing OSTree-managed files.
In the example of `/usr/local`, OSTree commits can ship content there,
all while allowing users to e.g. add scripts in `/usr/local/bin` when
booted into that commit.
Some reconciliation logic is executed whenever the base is updated so
that newer files in the base are never shadowed by a copied up version
in the upper directory. This matches RPM semantics when upgrading
packages whose files may have been modified.
For ease of integration, this is exposed as a systemd template unit which
any downstream distro/user can enable. The instance name is the mountpath
in escaped systemd path notation (e.g.
`ostree-state-overlay@usr-local.service`).
See discussions in https://github.com/ostreedev/ostree/issues/3113 for
more details.
2023-12-15 00:46:14 +03:00
$(addprefix man/html/,$(man8_files:.8=.html)) \
2021-05-21 20:57:54 +03:00
$(NULL)
if ENABLE_MAN_HTML
noinst_DATA += $(manhtml_files)
# Convenience target for building the just the HTML man pages
manhtml: $(manhtml_files)
endif
Add concept of state overlays
In the OSTree model, executables go in `/usr`, state in `/var` and
configuration in `/etc`. Software that lives in `/opt` however messes
this up because it often mixes code *and* state, making it harder to
manage.
More generally, it's sometimes useful to have the OSTree commit contain
code under a certain path, but still allow that path to be writable by
software and the sysadmin at runtime (`/usr/local` is another instance).
Add the concept of state overlays. A state overlay is an overlayfs
mount whose upper directory, which contains unmanaged state, is carried
forward on top of a lower directory, containing OSTree-managed files.
In the example of `/usr/local`, OSTree commits can ship content there,
all while allowing users to e.g. add scripts in `/usr/local/bin` when
booted into that commit.
Some reconciliation logic is executed whenever the base is updated so
that newer files in the base are never shadowed by a copied up version
in the upper directory. This matches RPM semantics when upgrading
packages whose files may have been modified.
For ease of integration, this is exposed as a systemd template unit which
any downstream distro/user can enable. The instance name is the mountpath
in escaped systemd path notation (e.g.
`ostree-state-overlay@usr-local.service`).
See discussions in https://github.com/ostreedev/ostree/issues/3113 for
more details.
2023-12-15 00:46:14 +03:00
EXTRA_DIST += man/index.xml $(man1_MANS:.1=.xml) $(man5_MANS:.5=.xml) $(man8_MANS:.8=.xml)
2016-01-27 20:51:07 +03:00
2021-05-21 20:57:54 +03:00
XSLT_MAN_STYLESHEET = http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl
2022-04-09 00:30:23 +03:00
XSLT_HTML_STYLESHEET = man/html.xsl
EXTRA_DIST += $(XSLT_HTML_STYLESHEET)
2016-01-27 20:51:07 +03:00
XSLTPROC_FLAGS = \
--nonet \
--stringparam man.output.quietly 1 \
--stringparam funcsynopsis.style ansi \
--stringparam man.th.extra1.suppress 1 \
--stringparam man.authors.section.enabled 0 \
--stringparam man.copyright.section.enabled 0
XSLTPROC_MAN = $(XSLTPROC) $(XSLTPROC_FLAGS)
%.1: %.xml
2021-05-21 20:57:54 +03:00
$(AM_V_GEN) $(XSLTPROC_MAN) --output $@ $(XSLT_MAN_STYLESHEET) $<
2016-01-27 20:51:07 +03:00
%.5: %.xml
2021-05-21 20:57:54 +03:00
$(AM_V_GEN) $(XSLTPROC_MAN) --output $@ $(XSLT_MAN_STYLESHEET) $<
Add concept of state overlays
In the OSTree model, executables go in `/usr`, state in `/var` and
configuration in `/etc`. Software that lives in `/opt` however messes
this up because it often mixes code *and* state, making it harder to
manage.
More generally, it's sometimes useful to have the OSTree commit contain
code under a certain path, but still allow that path to be writable by
software and the sysadmin at runtime (`/usr/local` is another instance).
Add the concept of state overlays. A state overlay is an overlayfs
mount whose upper directory, which contains unmanaged state, is carried
forward on top of a lower directory, containing OSTree-managed files.
In the example of `/usr/local`, OSTree commits can ship content there,
all while allowing users to e.g. add scripts in `/usr/local/bin` when
booted into that commit.
Some reconciliation logic is executed whenever the base is updated so
that newer files in the base are never shadowed by a copied up version
in the upper directory. This matches RPM semantics when upgrading
packages whose files may have been modified.
For ease of integration, this is exposed as a systemd template unit which
any downstream distro/user can enable. The instance name is the mountpath
in escaped systemd path notation (e.g.
`ostree-state-overlay@usr-local.service`).
See discussions in https://github.com/ostreedev/ostree/issues/3113 for
more details.
2023-12-15 00:46:14 +03:00
%.8: %.xml
$(AM_V_GEN) $(XSLTPROC_MAN) --output $@ $(XSLT_MAN_STYLESHEET) $<
2021-05-21 20:57:54 +03:00
man/html/%.html: man/%.xml
@mkdir -p man/html
$(AM_V_GEN) $(XSLTPROC_MAN) --output $@ $(XSLT_HTML_STYLESHEET) $<
2016-01-27 20:51:07 +03:00
CLEANFILES += \
$(man1_MANS) \
$(man5_MANS) \
Add concept of state overlays
In the OSTree model, executables go in `/usr`, state in `/var` and
configuration in `/etc`. Software that lives in `/opt` however messes
this up because it often mixes code *and* state, making it harder to
manage.
More generally, it's sometimes useful to have the OSTree commit contain
code under a certain path, but still allow that path to be writable by
software and the sysadmin at runtime (`/usr/local` is another instance).
Add the concept of state overlays. A state overlay is an overlayfs
mount whose upper directory, which contains unmanaged state, is carried
forward on top of a lower directory, containing OSTree-managed files.
In the example of `/usr/local`, OSTree commits can ship content there,
all while allowing users to e.g. add scripts in `/usr/local/bin` when
booted into that commit.
Some reconciliation logic is executed whenever the base is updated so
that newer files in the base are never shadowed by a copied up version
in the upper directory. This matches RPM semantics when upgrading
packages whose files may have been modified.
For ease of integration, this is exposed as a systemd template unit which
any downstream distro/user can enable. The instance name is the mountpath
in escaped systemd path notation (e.g.
`ostree-state-overlay@usr-local.service`).
See discussions in https://github.com/ostreedev/ostree/issues/3113 for
more details.
2023-12-15 00:46:14 +03:00
$(man8_MANS) \
2021-05-21 20:57:54 +03:00
$(manhtml_files) \
2016-01-27 20:51:07 +03:00
$(NULL)
2016-01-28 23:22:10 +03:00
endif
