Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document package layering via systemd #294

Merged
merged 9 commits into from
May 27, 2021
Merged

Document package layering via systemd #294

Show file tree
Hide file tree
Changes from 5 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
fe03bdd
Add package layering
rugk May 18, 2021
ffbf26d
fix: grammar
rugk May 18, 2021
b217ae0
fix: service name had superflous word
rugk May 18, 2021
30177fe
Fix superflous space
rugk May 24, 2021
f5b9943
fix: add online target and boot completion
rugk May 24, 2021
8d9cbb7
Fix typo
rugk May 26, 2021
01f50a7
Fix spelling
rugk May 26, 2021
1e9652e
Remove first-boot-complete.target
rugk May 26, 2021
e29fbfc
Improve package repository link
rugk May 26, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions modules/ROOT/nav.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,7 @@
** xref:running-containers.adoc[Running Containers]
** xref:authentication.adoc[Configuring Users and Groups]
** xref:hostname.adoc[Setting a Hostname]
** xref:layering-packages.adoc[Layering packages on the host system]
** xref:customize-nic.adoc[How to Customize a NIC Name]
** xref:sysconfig-configure-swaponzram.adoc[Configuring SwapOnZRAM]
** xref:sysconfig-configure-wireguard.adoc[Configuring WireGuard]
Expand Down
60 changes: 60 additions & 0 deletions modules/ROOT/pages/layering-packages.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
= Layering packages on the host system

To make other software accessible on the host system installation you can use https://coreos.github.io/rpm-ostree/[`rpm-ostree install`] to layer rpm packages. By default, packages are downloaded from the https://src.fedoraproject.org/[Fedora repository].

[NOTE]
====
It is recommend to use layering only if there is no other possible containerisation option.
The intention of Fedora CoreOS is to keep the base image as simple and small as possible for security and maintainability reasons. That is why you should in general prefer the usage of `podman` containers over layering software.
====

To start the layering of a package, you need to write an systemd unit that executes the `rpm-ostree` command to install the wanted package(s).
Changes are applied to a new deployment and a reboot is necessary for those to take effect.

== Example: Layering nano and setting it as the default editor

This example shows on how to install the text editor `nano` and add a script to `/etc/profile.d` so that it is set as the default editor for all users.
The parameter `--allow-inactive` is useful if the package is added to the root image in a future Fedora CoreOS release. In such a case, the parameter prevents that the service would fail.

NOTE: In the future, we will have a more Ignition-friendly method of doing this with stronger guarantees. See upstream issues https://github.com/coreos/butane/issues/81[butane#81] and https://github.com/coreos/fedora-coreos-tracker/issues/681[fedora-coreos-tracker#681] for more information.

NOTE: The `After=systemd-machine-id-commit.service` directive is important in the following examples to avoid some subtle issues. Similarly, any `ConditionFirstBoot=true` services should use `Before=first-boot-complete.target systemd-machine-id-commit.service`. See https://github.com/systemd/systemd/blob/3045c416e1cbbd8ab40577790522217fd1b9cb3b/man/systemd.unit.xml#L1315[the systemd documentation] for more details.

[source,yaml]
----
variant: fcos
version: 1.3.0
systemd:
units:
# installing nano as a layered package with rpm-ostree
- name: rpm-ostree-install-nano.service
enabled: true
contents: |
[Unit]
Description=Layer nano with rpm-ostree
# We run after `systemd-machine-id-commit.service` to ensure that
# `ConditionFirstBoot=true` services won't rerun on the next boot.
After=systemd-machine-id-commit.service
After=network-online.target
WantedBy=first-boot-complete.target
ConditionPathExists=!/var/lib/rpm-ostree-install-nano.stamp

[Service]
Type=oneshot
RemainAfterExit=yes
ExecStart=/usr/bin/rpm-ostree install --allow-inactive nano
ExecStart=/bin/touch /var/lib/rpm-ostree-install-nano.stamp
ExecStart=/bin/systemctl --no-block reboot
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We had a long thread on this somewhere; the problem with rebooting like this is it doesn't compose - what if e.g. two units want to reboot? They'll race, but you only want to reboot once.

What I think would be cleanest is having something like a coreos-firstboot-reboot.service that is off by default and is ordered After=first-boot-complete.target - that way multiple units can request a reboot via Wants=coreos-firstboot-reboot.service.

Copy link
Contributor Author

@rugk rugk May 24, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We had a long thread on this somewhere

Likely when you’ve discussed the cgroups example, because I’ve literally taken it from there and it’s also still there – so if we’d change that, we would possibly need to adjust it there, don’t we?

What I think would be cleanest is having something like a coreos-firstboot-reboot.service that is off by default

Okay, so is this something an admin should configure?
Or is this a service that should be included in Fedora CoreOS, so that an admin should only do Wants=coreos-firstboot-reboot.service as you say?

Again, we can hardly explain that on two totally separate pages… so I’d tend to having that included in FCOS.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For package layering in specific, I think the end goal for coreos/fedora-coreos-tracker#681 is that the packages are available from first boot so that you wouldn't have to reboot at all.


[Install]
WantedBy=multi-user.target
storage:
files:
# use nano as default editor
- path: /etc/profile.d/nano.sh
overwrite: true
contents:
inline: |
#/bin/sh
export EDITOR=nano
----