Skip to content
Snippets Groups Projects
Commit 3a5dddbf authored by Peter Senna Tschudin's avatar Peter Senna Tschudin
Browse files

Update REAME.md to match psdk interactive mode 


psdk is now interactive and does not require the user to discover disk
nodes before using the persistent disk. This patch updates the README.md
file to reflect the new usage.

Signed-off-by: default avatarPeter Senna Tschudin <peter.senna@collabora.com>
parent 4a9761a3
No related branches found
No related tags found
3 merge requests!7v2021 ← v2022dev1: Fix build,!6Push out some old unreleased commits,!4Update REAME.md to match psdk interactive mode
Hide whitespace changes
Inline Side-by-side
Showing
with 81 additions and 260 deletions
README.md
+ 81
− 260
View file @ 3a5dddbf
# Introduction
The Apertis Persistent SDK Tool is a package that contains a command line tool
named psdk. This tool helps the developer to decouple user files from the
Apertis SDK. The idea is to use a second disk that can be attached to more than
one SDK to store:
psdk is tool that helps the developer to decouple user files from the Apertis
SDK. The idea is to use a second disk that can be attached to more than one SDK
to store:
- /home
- /opt
- Configuration files selected by the developer
- /etc/cntlm.conf
- Other configuration files selected by the developer
The background information about the design of psdk can be found at:
https://designs.apertis.org/private/latest/maintaining-workspace-across-sdk-updates.html
Calling psdk without arguments will start the interactive mode. However it has the following options:
user@apertis:~$ psdk -h
usage: psdk [-h] [-e] [-s] [-c] [-i] [path]
positional arguments:
path Path to disk device node, e.g. /dev/vdb or to a
configuration file, e.g. /etc/apt/sources.list
optional arguments:
-h, --help show this help message and exit
Configuration files management:
-e, --etc Move a configuration file to the persistent storage. Use
this option once for each file you want to move to the
persistent storage. Usage: psdk -e /etc/configuration.file.
A backup of the original file will be at
/etc/configuration.file.PSDK. Use the original path (e.g.
/etc/configuration.file) to make changes to a file after
moving it to the persistent storage.
-s, --scan Scan persistent storage for configuration files and
configures the SDK to use each configuration file found.
Persistent disk management:
-c, --configure Configure this SDK to use use an already initialized disk
for persistent workspace. Usage: psdk --configure /dev/sdb
(replace sdb by the correct path to the disk containing the
persistent workspace)
-i, --init Initialize a new disk for persistent workspace. Files from
/home and from /opt will be copied from this SDK. After
initializing the disk psdk will configure this SDK to use
the persistent disk. Usage: psdk --init /dev/sdb (replace
sdb by the correct path to the disk you want to use)
user@apertis:~$ psdk -h
usage: psdk [-h] [-e] [-s] [-c] [-i] [path]
positional arguments:
path Path to a configuration file e.g. /etc/apt/sources.list
optional arguments:
-h, --help show this help message and exit
Configuration files management:
-e, --etc Move a configuration file to the persistent storage. Use
this option once for each file you want to move to the
persistent storage. Usage: psdk -e /etc/configuration.file.
A backup of the original file will be at
/etc/configuration.file.PSDK. Use the original path (e.g.
/etc/configuration.file) to make changes to a file after
moving it to the persistent storage.
-s, --scan Scan persistent storage for configuration files and
configures the SDK to use each configuration file found.
Persistent disk management:
-c, --configure Configure this SDK to use use an already initialized disk
for persistent workspace.
-i, --init Initialize a new disk for persistent workspace. Files from
/home and from /opt will be copied from this SDK. After
initializing the disk psdk will configure this SDK to use
the persistent disk.
# Using psdk to upgrade to a new version of the SDK
......@@ -54,77 +50,37 @@ workspace. There is one VirtualBox image for each version of the SDK, and
before psdk a version upgrade required each developer to manually migrate their
SDK customization to the new version.
psdk automates the tasks of moving the developer customization to a second
disk and configuring the SDK to use the second disk.
psdk automates the tasks of moving the developer customization (/home, /opt,
and /etc/cntlm.conf) to a second disk and configuring the SDK to use the second
disk.
## Upgrading to a new SDK using psdk interactive mode
First step is to prepare the persistent disk on the old SDK. Start by adding a
second disk to the old SDK. This disk should be big enough to host the contents
of /home and /opt: We recommend using more than 40GiB and no less than 20GiB.
As we will use dynamically allocated VDI images the unused space does not
consume disk space on the host, so if in doubt, create a larger disk. Step by
step instructions of how to add a second disk are on the section *Upgrading to
a new SDK using psdk*.
After adding the second disk, start the old SDK and click on the Desktop icon
*Persistent Disk Setup*. psdk will open in interactive mode, and it will show:
Persistent disk setup
For help visit:
https://developer.apertis.org/latest/sdk-usage.html
Status:
Empty disk found: /dev/sdb
Do you want to initialize the empty disk /dev/sdb and configure the SDK to use it as persistent disk?
(yes and press enter):
second disk to the old SDK on VirtualBox. This disk should be big enough to
host the contents of /home and /opt: We recommend using more than 40GiB and no
less than 20GiB. As we will use dynamically allocated VDI images the unused
space does not consume disk space on the host, so if in doubt, create a larger
disk. Step by step instructions of how to add a second disk are on the section
*Detailed instructions on upgrading to a new SDK using psdk*.
Typing *yes* and pressing enter will initialize the disk, will configure the
SDK, and will reboot the SDK to apply the changes.
After adding the second disk, start the old SDK and click on the psdk icon:
Applications -> System -> *Persistent Disk Setup*. psdk will open in
interactive mode, and will guide you trough the processes of initializing the
new disk and configuring the SDK to use it.
Turn off the old SDK.
After psdk is done, it will reboot the SDK. Wait for the reboot to complete,
and turn off the old SDK.
Now on the new SDK add the persistent disk you configured on the old SDK.
Detailed instructions on how to do this are on step 5 of section *Upgrading to
a new SDK using psdk*.
On VirtualBox add the persistent disk you configured on the old SDK to the new
SDK. Detailed instructions on how to do this are on step 5 of section
*Detailed instructions on upgrading to a new SDK using psdk*.
Start the new SDK and click on the Desktop icon *Persistent Disk Setup*. psdk
will open in interactive mode, and it will show:
Start the new SDK and click on the psdk icon: Applications -> System ->
*Persistent Disk Setup*. psdk will open in interactive mode, and will guide you
trough the processes of configuring the SDK to use the persistent disk.
Persistent disk setup
For help visit:
https://developer.apertis.org/latest/sdk-usage.html
Status:
Persistent disk in use: False
Persistent disk found: /dev/sdb1
Do you want to configure the SDK to use the persistent disk /dev/sdb1?
(yes and press enter):
Typing *yes* and pressing enter will configure the SDK to use the persistent
disk and will reboot the SDK to apply the changes.
## Upgrading to a new SDK using psdk (short version)
- On the old SDK:
- Add a new second disk to be used as persistent storage
- Call `psdk -i /dev/sdb` assuming sdb points to the new disk
- Reboot
- Call `psdk -e /etc/file` for each configuration file you want
on persistent storage
- Shutdown the SDK
- On the new SDK:
- Add the persistent disk you configured on the old SDK as second disk
- Call `psdk -c /dev/sdb` assuming sdb points to the new disk
- Reboot
- Call `psdk -s` to use the configuration files that are on the
persistent storage
- Reboot
## Upgrading to a new SDK using psdk
## Detailed instructions on upgrading to a new SDK using psdk
ATTENTION: Do not use VirtualBox *Shareable hard disks* expert feature. ext4
file system is not prepared to handle this feature, and using it will lead to
......@@ -151,111 +107,42 @@ disk space on the host, so if in doubt, create a larger disk.
than 20GiB and preferably more than 40GiB.
- Click on Create
2 - Start the old SDK virtual machine and locate the new disk using
`sudo fdisk -l`:
user@oldSDK:~$ sudo fdisk -l
Disk /dev/sdb: 40 GiB, 42949672960 bytes, 83886080 sectors
Disk model: VBOX HARDDISK
Units: sectors of 1 * 512 = 512 bytes
Sector size (logical/physical): 512 bytes / 512 bytes
I/O size (minimum/optimal): 512 bytes / 512 bytes
Disk /dev/sda: 18.6 GiB, 20000000000 bytes, 39062500 sectors
Disk model: VBOX HARDDISK
Units: sectors of 1 * 512 = 512 bytes
Sector size (logical/physical): 512 bytes / 512 bytes
I/O size (minimum/optimal): 512 bytes / 512 bytes
Disklabel type: gpt
Disk identifier: 1112CA3E-EC00-4BC6-9A47-48DF7AD20425
Device Start End Sectors Size Type
/dev/sda1 6176 500000 493825 241.1M EFI System
/dev/sda2 500001 19531250 19031250 9.1G Linux filesystem
/dev/sda3 19531251 39062466 19531216 9.3G Linux filesystem
The new disk is /dev/sdb because it has no partitions and it has the same size
of the disk created on VirtualBox.
3 - Initialize the persistent disk and configure the SDK to use the persistent
disk:
Calling `psdk -i /dev/sdb` will prepare the persistent disk, copy the contents
of /home and /opt to the persistent disk and finally configure the SDK to use
the persistent disk.
user@oldSDK:~$ psdk -i /dev/sdb
Initializing the persistent disk...
Will partition the persistent storage disk...
Will format the persistent storage partition...
mke2fs 1.44.5 (15-Dec-2018)
Creating filesystem with 5242619 4k blocks and 1310720 inodes
Filesystem UUID: 573907cc-2cb1-4246-9c10-6909433f5689
Superblock backups stored on blocks:
32768, 98304, 163840, 229376, 294912, 819200, 884736, 1605632, 2654208,
4096000
Allocating group tables: done
Writing inode tables: done
Creating journal (32768 blocks): done
Writing superblocks and filesystem accounting information: done
Will copy contents of /home to persistent storage...
'/home/./sysroot' -> '/run/media/persistent/./sysroot'
'/home/./user' -> '/run/media/persistent/./user'
'/home/./user/Pictures' -> '/run/media/persistent/./user/Pictures'
'/home/./user/.config' -> '/run/media/persistent/./user/.config'
'/home/./user/.config/xfce4' -> '/run/media/persistent/./user/.config/xfce4'
...
Will copy contents of /opt to persistent storage...
'/opt/devroot' -> '/run/media/persistent/opt/devroot'
'/opt/devroot/opt' -> '/run/media/persistent/opt/devroot/opt'
'/opt/devroot/proc' -> '/run/media/persistent/opt/devroot/proc'
'/opt/devroot/tmp' -> '/run/media/persistent/opt/devroot/tmp'
'/opt/devroot/etc' -> '/run/media/persistent/opt/devroot/etc'
...
Configuring the SDK to use the persistent storage...
Please reboot the SDK for the changes to take effect.
Reboot the SDK
2 - Start the old SDK virtual machine and call psdk:
- Applications -> System -> *Persistent Disk Setup*
- psdk will open in interactive mode, and will guide you trough the processes
of initializing the new disk and configuring the SDK to use it.
- When it is done, psdk will reboot the SDK. Wait for the reboot to complete.
user@oldSDK:~$ sudo reboot
2(a) - Moving more configuration files to the persistent storage
4 - Moving configuration files to the persistent storage
This is an optional step. By default psdk will move /etc/cntlm.conf to the
persistent storage, but you can also move other configuration files.
After rebooting the SDK you will be able to move configuration files to the
persistent storage using `psdk -e /etc/file`. Let's move `/etc/cntlm.conf` to
the persistent storage as an example:
- Before starting make sure that step 2 was completed and that the SDK has
rebooted after configuring the persistent storage.
- For each configuration file you want on persistent storage open a terminal
and call `psdk -e /etc/file`. As an example:
user@oldSDK:~$ psdk -e /etc/cntlm.conf
user@oldSDK:~$ psdk -e /etc/xfce4/defaults.list
Configuration file moved to persistent storage. From now on, changes made to
/etc/cntlm.conf will be saved on the persistent storage.
/etc/xfce4/defaults.list will be saved on the persistent storage.
Here is what psdk -e does:
- Copy the contents of the configuration file to the persistent storage
dereferencing symbolic links.
- Rename the configuration file to add the .PSDK extension. So in our
example the backup will be at /etc/cntlm.conf.PSDK.
example the backup will be at /etc/xfce4/defaults.list.PSDK.
- Create a symbolic link from the persistent storage to the
configuration file.
After call `psdk -e /etc/cntlm.conf`, you can continue to use the configuration
file /etc/cntlm.conf normally. Any changes made will be saved on the persistent
storage.
Repeat this step for each configuration file you want on the persistent
storage. Notice that `psdk -e` only accept files as argument. No directories
are allowed.
After call `psdk -e /etc/xfce4/defaults.list`, you can continue to use the
configuration file /etc/xfce4/defaults.list normally. Any changes made will be
saved on the persistent storage.
After you are done, power off the old SDK.
3 - Power off the old SDK
After you are done with the persistent storage, power off the old SDK.
5 - On the new SDK add the persistent disk you configured on the old SDK:
4 - Add the persistent disk to the new SDK. On VirtualBox:
- Go to Settings of the new SDK Virtual Machine
- Go to Storage
- Select Controller SATA
......@@ -265,85 +152,19 @@ After you are done, power off the old SDK.
and then on Choose.
- Click on OK
6 - Start the new SDK virtual machine and locate the new disk using
`sudo fdisk -l`:
user@newSDK:~$ sudo fdisk -l
Disk /dev/sda: 18.6 GiB, 20000000000 bytes, 39062500 sectors
Disk model: VBOX HARDDISK
Units: sectors of 1 * 512 = 512 bytes
Sector size (logical/physical): 512 bytes / 512 bytes
I/O size (minimum/optimal): 512 bytes / 512 bytes
Disklabel type: gpt
Disk identifier: 1112CA3E-EC00-4BC6-9A47-48DF7AD20425
Device Start End Sectors Size Type
/dev/sda1 6176 500000 493825 241.1M EFI System
/dev/sda2 500001 19531250 19031250 9.1G Linux filesystem
/dev/sda3 19531251 39062466 19531216 9.3G Linux filesystem
Disk /dev/sdb: 40 GiB, 42949672960 bytes, 83886080 sectors
Disk model: VBOX HARDDISK
Units: sectors of 1 * 512 = 512 bytes
Sector size (logical/physical): 512 bytes / 512 bytes
I/O size (minimum/optimal): 512 bytes / 512 bytes
Disklabel type: gpt
Disk identifier: 25C02522-9601-3447-9DCF-D426C27B7C75
Device Start End Sectors Size Type
/dev/sdb1 2048 41943006 41940959 40G Linux filesystem
Now both disks are initialized, and /dev/sda seems to be the SDK disk. To find
out if the partition /dev/sdb1 contains the persistent storage we can call
`sudo e2label /dev/sdb1`:
user@newSDK:~$ sudo e2label /dev/sdb1
sdk-persistent
The partion has the label 'sdk-persistent' menaing that our persistent disk is
/dev/sdb.
7 - Configure the SDK to use the persistent disk:
Calling `psdk -c /dev/sdb` will configure the SDK to use the persistent disk.
user@newSDK:~$ psdk -c /dev/sdb
Configuring the SDK to use the persistent storage...
Created symlink /etc/systemd/system/default.target.wants/run-media-root-opt.mount → /etc/systemd/system/run-media-root-opt.mount.
Created symlink /etc/systemd/system/default.target.wants/run-media-root-home.mount → /etc/systemd/system/run-media-root-home.mount.
Created symlink /etc/systemd/system/default.target.wants/opt.mount → /etc/systemd/system/opt.mount.
Please reboot the SDK for the changes to take effect.
Reboot the SDK
user@newSDK:~$ sudo reboot
8 - Using configuration files from the persistent storage
After rebooting the SDK you will be able to use configuration files from the
persistent storage. You need to call `psdk -s` once to scan the persistent
storage for configuration files and use them:
user@newSDK:~$ psdk -s
Using configuration file found on persistent storage. From now on,
changes made to /etc/cntlm.conf will be saved on the persistent storage.
Depending on which files were altered on /etc, you will need to reboot:
user@newSDK:~$ sudo reboot
5 - Configure the new SDK to use the persistent disk:
Start the new SDK and click on the psdk icon: Applications -> System ->
*Persistent Disk Setup*. psdk will open in interactive mode, and will guide you
trough the processes of configuring the SDK to use the persistent disk.
# Where are the old files and folders?
The old /home and /opt directories are accessible from /run/media/root/. A
backup copy of configuration files that were moved to the persistent are kept
on /etc with the extension .PSDK.
# Recovering the SDK
If you accidentally delete the persistent disk of an SDK, the SDK will not
longer boot. To fix an SDK that does not book due missig persistent disk:
longer boot. To fix an SDK that does not book due missing persistent disk:
- Stop the SDK bootloader from automatically booting. To do so you need to
press space a few times. When you succeed the bootloader will show you a menu
with two options: Apertis and Reboot to Firmware Interface
......@@ -352,7 +173,7 @@ longer boot. To fix an SDK that does not book due missig persistent disk:
these, but delete everything else.
- Add init=/bin/sh at the end of the line
- Press enter to boot
- Remount the filesystem with write permissions: mount -o remount,rw /
- Remount the file system with write permissions: mount -o remount,rw /
- Fixing the SDK involves editing /etc/fstab, removing .mount files from
/etc/systemd/system, and fixing files on /etc that are links to the persistent
storage.
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
Apertis Website Terms of Use Privacy Policy