From faa30c752633303baf53cf61de5bae42f43f6ab0 Mon Sep 17 00:00:00 2001 From: Mark Doffman Date: Tue, 1 Apr 2014 03:27:53 +0000 Subject: Add help files for nfsboot, rawdisk and tar. Begin adding help documentation for configuration and write extensions starting with nfsboot.write, rawdisk.write and tar.write. --- rawdisk.write.help | 7 +++++++ 1 file changed, 7 insertions(+) create mode 100644 rawdisk.write.help (limited to 'rawdisk.write.help') diff --git a/rawdisk.write.help b/rawdisk.write.help new file mode 100644 index 00000000..a514a4e8 --- /dev/null +++ b/rawdisk.write.help @@ -0,0 +1,7 @@ +help: | + Create a raw disk image during Morph's deployment. + + If the image already exists, it is upgraded. + + The `location` argument is a pathname to the image to be + created or upgraded. -- cgit v1.2.1 From 3a8c02eb8d9beac6ec6c0570c9a50de72b23fc52 Mon Sep 17 00:00:00 2001 From: Richard Maw Date: Mon, 2 Jun 2014 11:09:29 +0000 Subject: Add initramfs support to write extensions that produce disks If INITRAMFS_PATH is specified and the file exists, then the produced kernel command line will use root=UUID=$uuid_of_created_disk rather than root=/dev/sda, which may be incorrect. Help files have been updated to mention the new option. This leads to an unfortunate duplication of the path to the initramfs, in both the location field of the nested deployment and the INITRAMFS_PATH of the disk image creation. However, an initramfs could be produced by a chunk and put in the same place, so it doesn't make sense to couple the rawdisk and initramfs write extensions to remove this duplication. Similarly, there may be multiple valid initramfs in the rootfs e.g. extlinux loads a hypervisor, which is Linux + initramfs, and the initramfs then boots a guest Linux system, which uses a different initramfs. This makes it important to explicitly let the rootfs write extensions know which to use, or not as the case may be. util-linux's blkid is required, since the busybox version ignores the options to filter its output, and parsing the output is undesirable. Because syslinux's btrfs subvolume support is limited to being able to use a non-0 default subvolume, the initramfs has to be copied out of the run-time rootfs subvolume and into the boot subvolume. This pushed the required disk space of a minimal system over the 512M threshold because we do not have the userland tooling support to be able to do a btrfs file contents clone. --- rawdisk.write.help | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'rawdisk.write.help') diff --git a/rawdisk.write.help b/rawdisk.write.help index a514a4e8..298d441c 100644 --- a/rawdisk.write.help +++ b/rawdisk.write.help @@ -5,3 +5,7 @@ help: | The `location` argument is a pathname to the image to be created or upgraded. + + The INITRAMFS_PATH option can be used to specify the location of an + initramfs for syslinux to tell Linux to use, rather than booting + the rootfs directly. -- cgit v1.2.1 From 3599f68c40dc74f5634801b9c3ced856cf91155d Mon Sep 17 00:00:00 2001 From: Pete Fotheringham Date: Fri, 5 Dec 2014 09:02:34 +0000 Subject: rawdisk write extension documentation --- rawdisk.write.help | 42 ++++++++++++++++++++++++++++++++++-------- 1 file changed, 34 insertions(+), 8 deletions(-) (limited to 'rawdisk.write.help') diff --git a/rawdisk.write.help b/rawdisk.write.help index 298d441c..f225276d 100644 --- a/rawdisk.write.help +++ b/rawdisk.write.help @@ -1,11 +1,37 @@ help: | - Create a raw disk image during Morph's deployment. - - If the image already exists, it is upgraded. - The `location` argument is a pathname to the image to be - created or upgraded. + Write a system produced by Morph to a physical disk, or to a file that can + be used as a virtual disk. The target will be formatted as a single Btrfs + partition, with the system image written to a subvolume in /systems, and + other subvolumes created for /home, /opt, /root, /srv and /var. - The INITRAMFS_PATH option can be used to specify the location of an - initramfs for syslinux to tell Linux to use, rather than booting - the rootfs directly. + When written to a physical drive, the drive can be used as the boot device + for a 'real' machine. + + When written to a file, the file can be used independently of `morph` to + create virtual machines with KVM / libvirt, OpenStack or, after converting + it to VDI format, VirtualBox. + + `morph deploy` will fail if the file specified by `location` already exists. + + If used in `morph upgrade`, the rootfs produced by 'morph build' is added to + the existing raw disk image or device as an additional btrfs sub-volume. + `morph upgrade` will fail if the file specified by `location` does not + exist, or is not a Baserock raw disk image. (Most users are unlikely to need + or use this functionality: it is useful mainly for developers working on the + Baserock tools.) + + Parameters: + + * location: the pathname of the disk image to be created/upgraded, or the + path to the physical device. + + * VERSION_LABEL=label - should contain only alpha-numeric + characters and the '-' (hyphen) character. Mandatory if being used with + `morph update` + + * INITRAMFS_PATH=path: the location of an initramfs for the bootloader to + tell Linux to use, rather than booting the rootfs directly. + + (See `morph help deploy` for details of how to pass parameters to write + extensions) -- cgit v1.2.1 From 6c1cc0f3706d1019158b6a31735f416b974a1226 Mon Sep 17 00:00:00 2001 From: Sam Thursfield Date: Tue, 9 Dec 2014 17:49:36 +0000 Subject: deploy: Note that some of the extensions listed live in definitions.git The user should be aware of this because if they aren't building baserock:baserock/definitions or a repo forked from it, those extensions won't be available. Also fix some long lines that I seem to have failed to commit already. --- rawdisk.write.help | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) (limited to 'rawdisk.write.help') diff --git a/rawdisk.write.help b/rawdisk.write.help index f225276d..81f35024 100644 --- a/rawdisk.write.help +++ b/rawdisk.write.help @@ -12,14 +12,15 @@ help: | create virtual machines with KVM / libvirt, OpenStack or, after converting it to VDI format, VirtualBox. - `morph deploy` will fail if the file specified by `location` already exists. + `morph deploy` will fail if the file specified by `location` already + exists. - If used in `morph upgrade`, the rootfs produced by 'morph build' is added to - the existing raw disk image or device as an additional btrfs sub-volume. + If used in `morph upgrade`, the rootfs produced by 'morph build' is added + to the existing raw disk image or device as an additional btrfs sub-volume. `morph upgrade` will fail if the file specified by `location` does not - exist, or is not a Baserock raw disk image. (Most users are unlikely to need - or use this functionality: it is useful mainly for developers working on the - Baserock tools.) + exist, or is not a Baserock raw disk image. (Most users are unlikely to + need or use this functionality: it is useful mainly for developers working + on the Baserock tools.) Parameters: -- cgit v1.2.1 From 37ca9dae1b891d73f891448d32fbbd8d7120850c Mon Sep 17 00:00:00 2001 From: Pete Fotheringham Date: Fri, 12 Dec 2014 11:26:58 +0000 Subject: Document DTB_PATH write extension parameter --- rawdisk.write.help | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'rawdisk.write.help') diff --git a/rawdisk.write.help b/rawdisk.write.help index 81f35024..fe47c890 100644 --- a/rawdisk.write.help +++ b/rawdisk.write.help @@ -34,5 +34,10 @@ help: | * INITRAMFS_PATH=path: the location of an initramfs for the bootloader to tell Linux to use, rather than booting the rootfs directly. + * DTB_PATH=path: **(MANDATORY)** for systems that require a device tree + binary - Give the full path (without a leading /) to the location of the + DTB in the built system image . The deployment will fail if `path` does + not exist. + (See `morph help deploy` for details of how to pass parameters to write extensions) -- cgit v1.2.1 From 859568b79d22299c082a4108dd057b9145a13eda Mon Sep 17 00:00:00 2001 From: Pete Fotheringham Date: Fri, 12 Dec 2014 11:30:13 +0000 Subject: Document BOOTLOADER_INSTALL and BOOTLOADER_CONFIG_FORMAT write extension parameters --- rawdisk.write.help | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) (limited to 'rawdisk.write.help') diff --git a/rawdisk.write.help b/rawdisk.write.help index fe47c890..d6c78573 100644 --- a/rawdisk.write.help +++ b/rawdisk.write.help @@ -39,5 +39,21 @@ help: | DTB in the built system image . The deployment will fail if `path` does not exist. + * BOOTLOADER_INSTALL=value: the bootloader to be installed + **(MANDATORY)** for non-x86 systems + + allowed values = + - 'extlinux' (default) - the extlinux bootloader will + be installed + - 'none' - no bootloader will be installed by `morph deploy`. A + bootloader must be installed manually. This value must be used when + deploying non-x86 systems such as ARM. + + * BOOTLOADER_CONFIG_FORMAT=value: the bootloader format to be used. + If not specified for x86-32 and x86-64 systems, 'extlinux' will be used + + allowed values = + - 'extlinux' + (See `morph help deploy` for details of how to pass parameters to write extensions) -- cgit v1.2.1 From cb8811daf402a8485f0ca9fd678843f11aaaf5ea Mon Sep 17 00:00:00 2001 From: Pete Fotheringham Date: Fri, 12 Dec 2014 11:36:04 +0000 Subject: Document KERNEL_ARGS write extension parameter --- rawdisk.write.help | 9 +++++++++ 1 file changed, 9 insertions(+) (limited to 'rawdisk.write.help') diff --git a/rawdisk.write.help b/rawdisk.write.help index d6c78573..54af81c4 100644 --- a/rawdisk.write.help +++ b/rawdisk.write.help @@ -55,5 +55,14 @@ help: | allowed values = - 'extlinux' + * KERNEL_ARGS=args: optional additional kernel command-line parameters to + be appended to the default set. The default set is: + + 'rw init=/sbin/init rootfstype=btrfs \ + rootflags=subvol=systems/default/run \ + root=[name or UUID of root filesystem]' + + (See https://www.kernel.org/doc/Documentation/kernel-parameters.txt) + (See `morph help deploy` for details of how to pass parameters to write extensions) -- cgit v1.2.1 From 8ca2082cdb2cf65b8ec9e1c392349208c0a00373 Mon Sep 17 00:00:00 2001 From: Pete Fotheringham Date: Wed, 4 Mar 2015 13:28:57 +0000 Subject: Add copyright headers to write.help and configure.help files --- rawdisk.write.help | 14 ++++++++++++++ 1 file changed, 14 insertions(+) (limited to 'rawdisk.write.help') diff --git a/rawdisk.write.help b/rawdisk.write.help index 54af81c4..52ed73fb 100644 --- a/rawdisk.write.help +++ b/rawdisk.write.help @@ -1,3 +1,17 @@ +# Copyright (C) 2014, 2015 Codethink Limited +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; version 2 of the License. +# +# This program 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 General Public License for more details. +# +# You should have received a copy of the GNU General Public License along +# with this program; if not, see . + help: | Write a system produced by Morph to a physical disk, or to a file that can -- cgit v1.2.1