Package: deploy-ostree
deploy-ostree: deploy and provision an OSTree commitdeploy-ostreeis a tool to deploy and configure anOSTreecommit
without user input from a simple configuration file. It will:set up the remotepull the commitcreate the staterootcheck out and deploy the treerun additional provisioners to make the deployed system usefulIts original intended use case was automatic tests; accordingly, it should not
be seen as a replacement for an end-user installer.deploy-ostreecan serve
as a tool to install a regular system, but it may also take shortcuts and do
things in a way that are fine for a disposable test environment, but might not
be fine in long-lived system.RequirementsPython3.5 or newerOSTree2018.4 or newer (older versions may work, but weren't tested)Runningdeploy-ostreefrom inside a libostree deployment requires no
additional configuration (provided the bootloader is set up correctly). To rundeploy-ostreeon a system that's not using libostree, you need to first runostree admin init-fs /to set up the libostree system repository and directory
structure. In addition, you may need to set up the bootloader. How to do this
depends on the OS, the architecture, and the bootloader in use.InstallationYou can install deploy-ostree using pip:$pip3installdeploy-ostreeUsage#deploy-ostree<configpathorHTTPURL>This requires root permissions. Ifdeploy-ostreeexits successfully, your new
OSTree deployment should be ready to boot.Command-Line Arguments--sysroot=SYSROOT: install into the specified target root directory,
rather than/. Just like for/, the directory needs to exist and be
initialized for libostree use withostree admin init-fs <sysroot path>.--karg-root=ROOT: set the kernelrootboot parameter to the given value.
By default, therootparameter of the current boot is used.--fstab=FSTAB: copy the given file into the deployment as/etc/fstab. If
this parameter is omitted, the system fstab (/etc/fstab) is used.A Note on SELinuxWhile not recommended, certain combinations of SELinux-using host systems and
SELinux-using deployed systems might require disabling SELinux before deploying
to avoid clashes between the host's SELinux policies and the SELinux labels in
the deployed tree. To temporarily disable SELinux:#setenforce0Configuration FormatConfiguration files must be either validJSONorTOMLfiles. The
syntax of a configuration is determined by its file extension: if it's.toml(case-insensitive), it's parsed as a TOML file. Otherwise, it's considered a
JSON file. While the syntax of the formats obviously differs, the structure
used bydeploy-ostreeis the same for both, which means JSON configuration
files can be converted to TOML using a generic JSON-to-TOML converter (and
vice versa).Both formats use the same top-level configuration keys:urlorpath(required): path or URL to the OSTree repository to
pull from. Exactly one of these must be specified. If a relative path is
specified, it is interpreted relative to:if the configuration is a local file: the directory of the configuration
file.the current working directory otherwise.ref(required): OSTree commit to deploy.remote: name for the OSTree remote. If this remote already exists, it it
replaced. By default, a random name is used.stateroot: name of the OSTree stateroot to use. By default, a random name
is generated.kernel-args: list of additional kernel arguments. The root partition is
always determined and included in the kernel command line automatically.provisioners: list of provisioners to run after the OSTree commit is
checked out. This must be an array of objects. Each object defines a
provisioner based on the keys it contains. Different kinds of provisioners are
documented below.Script ProvisionersScript provisioners allow you to run custom script snippets defined inline in
your configuration file. These will be run in the deployment directory after
deployment, with both /etc and /var available.The script is specified with thescriptkey. The script text will be fed to
the interpreter over stdin. The interpreter is/bin/shby default, but can be
overridden using theinterpreterkey. Note that the interpreter needs to be
able to consume a script from stdin with no further arguments. An optional
description can be set with thedescriptionkey. This line will be shown
during deploying to describe the provisioning step.The working directory of the script is set to the root directory of the
deployment. Accordingly, any paths in the deployment should be relative to the
current directory. Note that the script is not chrooted in any way. This means
you can mess up the host system from your script if you're not careful!If you need to run binaries from the deployed system, you can manually chroot
into the deployment directory. Ultimately, you have to weigh depending on your
usecase whether you want to rely on the host system for any tools you need, or
whether you want to run things from the deployed system. Keep in mind that when
deploying cross-architecture, running binaries from the deployed system may not
work.JSON example:{"script":"echo my-system > ./etc/hostname","interpreter":"/bin/bash","description":"hostname"}TOML example:[[provisioners]]script="echo my-system > ./etc/hostname"interpreter="/bin/bash"description="hostname"Built-in ProvisionersThese are the provisioners included withdeploy-ostree. The name of the
provisioner must be set with the keybuiltinon the configuration object. Any
options documented below must also be specified in the provisioner configuration
object.JSON example:{"builtin":"root-password","password":"password"}TOML example:[[provisioners]]builtin="root-password"password="password"etc-network-interfacesSet up the loopback interface and one other interface for DHCP with/etc/network/interfaces. This probably only applies
to Debian-based systems and only for DHCP configuration. If you need different
configuration, you will have to supply your own provisioner or use something
like NetworkManager.interface: name of the interface to configure. By default, the default
network interface is retrieved from/proc/net/route. However, this might
differ between systems (especially if only one is usingpredictable interface names) so it's not guaranteed to work.root-passwordSet the root password.password(required): root password to set.create-userCreate a user. This does try to create the home directory, but if your system
requires anything more than the stateroot's/varbeing mounted, it may not
work.username(required): username of the user to create.password(required): password of the user to create.shell: shell for the user. If not specified, the default shell is used.passwordless-sudoSet up a user for passwordlesssudoaccess. For this to have any effect,sudomust be installed on your system.user(required): name of the user.authorized-keysCopy an SSHauthorized_keysfile from the host system into the deployed
system. This is useful inVagrantscenarios, as it allows you to copy
the SSH key used by Vagrant into the deployed system.path(required): path of the keys file to copy into the deployed system.
This is a path on the system that is runningdeploy-ostree, not in the
deployed system.user(required): name of the user to receive the keys. This must be a
user in the deployed system. The file is copied to.ssh/authorized_keysinside the user's home directory.machine-idCreate an/etc/machine-idfile containing a random UUID. If the file already
exists, it's not overwritten. This is necessary to get D-Bus to work on systems
that don't create a machine ID file on boot if missing.path: alternative path to the file. If missing,/etc/machine-idis used.
Any directories in the path that are missing will be created.Example ConfigThis configuration will download and deployCentOS Atomic Host,
set up/etc/fstab, and create a user and set it up for passwordlesssudo.JSON:{"url":"http://mirror.centos.org/centos/7/atomic/x86_64/repo/","ref":"centos-atomic-host/7/x86_64/standard","remote":"centos-atomic","stateroot":"centos-atomic-host","kernel-args":["quiet","splash"],"provisioners":[{"builtin":"create-user","username":"atomic","password":"atomic","shell":"/usr/bin/bash"},{"script":"echo centos-atomic-host > etc/hostname","description":"hostname"},{"builtin":"passwordless-sudo","user":"atomic"}]}TOML:url="http://mirror.centos.org/centos/7/atomic/x86_64/repo/"ref="centos-atomic-host/7/x86_64/standard"remote="centos-atomic"stateroot="centos-atomic-host"kernel-args=["quiet","splash"][[provisioners]]builtin="create-user"username="atomic"password="atomic"shell="/usr/bin/bash"[[provisioners]]script="echo centos-atomic-host > etc/hostname"description="hostname"[[provisioners]]builtin="passwordless-sudo"user="atomic"Note that CentOS Atomic Host includescloud-initwhich means it
will spend some time unsuccessfully doing its cloud setup. This is awkward, but
there's not a lot of OSTree systems to demonstrate with so here we are.Version HistorySeethe changelogfor a list of versions and their changes.