Normally Linux distribution ISOs work perfectly when written to a USB for booting as a 'Live USB' allowing both usage and installation of the distro. Unfortunately with the introduction of Intel Atom based mini PCs and tablets the issue of requiring a 32-bit bootloader to boot a 64-bit OS arose. Further complications were caused by the initial lack of 'mainline' support for HDMI audio and wifi/bluetooth resulting in either the need for custom kernels or for one of the more recent 'mainline' kernels. However because Ubuntu is not a 'rolling release' it is not possible to try the latest kernel or a specific kernel with a 'Live USB'. Now with the introduction of Intel Apollo Lake based mini PCs a new issue has arisen where GRUB simply fails to boot unless the device is one of the few with a BIOS option to select Linux as the OS. Whilst some Linux distros can work OOTB regardless of architecture and bootloader I found that for Ubuntu it wasn't that simple. To solve the limitations of using a standard ISO I developed a script that allows an ISO to be respun and customized ("remastered") to create a new ISO. Being a script which you run locally it means you can both see and control how your ISO is respun. The script offers the ability to:
The script is called 'isorespin.sh' and works with all official desktop 64-bit Ubuntu (http://releases.ubuntu.com) and Ubuntu flavoured ISOs (https://www.ubuntu.com/download/ubuntu-flavours), Linux Mint ISOs (https://www.linuxmint.com/download.php), KDE neon ISOs (https://neon.kde.org/download), elementary OS ISOs (https://elementary.io), Peppermint OS (https://peppermintos.com/) and BackBox Linux (https://backbox.org/). And whilst Kali is not directly supported the Kali Metapackages (https://tools.kali.org/kali-metapackages) can be added when respinning an ISO. It can be run using either the shell CLI (command line interface) in a the terminal or using its GUI (graphical user interface). Not only will it generate a new ISO but it will also produce a log file which includes the options used when respinning the ISO and serves to document the respun ISO. Before you start
Quick start guide to using 'isorespin.sh' 1. Open a terminal session on a host device running Ubuntu (or similar) e.g. your main PC 2. Download my 'isorespin.sh' script (click on the link) 3. Make the script executable by entering: sudo mv isorespin.sh /usr/local/bin sudo chmod 755 /usr/local/bin/isorespin.sh 4. Install the packages required for running (some will already be installed): sudo apt -y install p7zip-full bc klibc-utils iproute2 genisoimage dosfstools sudo apt -y install squashfs-tools rsync unzip wget findutils xorriso bsdutils 5. Download the ISO you want to respin (for example as 'ubuntu-16.04.3-desktop-amd64.iso') 6. Either run the script with GUI: isorespin.sh or run the script with options. Commonly used options include: Add a 32-bit bootloader isorespin.sh -i ubuntu-16.04.3-desktop-amd64.iso Respin the ISO suitable for booting on Intel Atom devices isorespin.sh -i ubuntu-16.04.3-desktop-amd64.iso --atom Respin the ISO suitable for booting on Intel Apollo Lake devices isorespin.sh -i ubuntu-16.04.3-desktop-amd64.iso --apollo Update the ISO with the latest mainline kernel isorespin.sh -i ubuntu-16.04.3-desktop-amd64.iso -u Update the ISO with a specific kernel version isorespin.sh -i ubuntu-16.04.3-desktop-amd64.iso -k v4.15-rc2 A new ISO prefixed with 'linuxium' as a minimum will be created. For example the command isorespin.sh -i ubuntu-16.04.3-desktop-amd64.iso -k v4.15-rc2 --apollo creates the ISO linuxium-apollo-v4.15-rc2-ubuntu-16.04.3-desktop-amd64.iso To get a list of all available options enter: isorespin.sh -h Note the script runs several commands as 'sudo' so you will be asked for your password [sudo] password for <username>: 7. Insert a USB and make a note of which device it is (use 'df', 'blkid' or 'lsblk' to confirm) 8. Unmount any files systems auto mounted from the USB sudo umount /dev/<USB device>* 9. Write the respun ISO to USB sudo dd if=<respun ISO> of=/dev/<USB device> bs=4M (e.g. sudo dd if=linuxium-apollo-v4.15-rc2-ubuntu-16.04.3-desktop-amd64.iso of=/dev/sdx bs=4M) 10. Boot the USB on your target device e.g. your mini PC The following sections explain each of the steps in more detail together with an issues section, how to report errors and how to donate.
Although it is expected to run the script on a Linux machine typically running 64-bit Ubuntu or a 64-bit Ubuntu based OS it also works on a Linux virtual machine on Windows (see below for further details). You will need certain packages like 'squashfs-tools' and 'xorriso' installed (use 'sudo apt-get install -y squashfs-tools xorriso' to install them) plus 'zenity' if you want to use the GUI. As different Linux distros have different packages installed by default the script will first check and notify you if any other packages are required. You will also need at least 10 GB of free space but this can be on external storage (e.g. a USB) as it can be specified as a location different to where the script is run from. For some options (such as updating the kernel) you will need a working internet connection as the script needs to download software. Also the script needs to be executable which can be achieved using the 'chmod' command ('sudo chmod 755 isorespin.sh'). As the script runs some commands (e.g. mount/umount) which require root access using the 'sudo' command you will initially be prompted for your password and must already have 'sudo' privileges. Finally some restrictions: you cannot respin an ISO that is EOL (End Of Life); you cannot respin an ISO on an OS that doesn't support 'systemd' when using the '--apollo' or the '-b Linuxium' options; you also cannot respin an ISO if the ISO doesn't support 'systemd' when using the '--atom', '--apollo' or '-b Linuxium' options. Invocation Running the script is really quite simple even though there are quite a lot of features or options making it look rather complex.
Usage: /usr/local/bin/isorespin.sh [ -h | -v | --check | --rolling-list ] /usr/local/bin/isorespin.sh -i <ISO> [ [ -u | -k <kernel> ] | [ --dist-upgrade | --upgrade ] | ... /usr/local/bin/isorespin.sh ... [ --rolling-release | --rolling-release-hwe | --rolling-release-hwe-edge | --rolling-proposed | --rolling-proposed-hwe | --rolling-proposed-hwe-edge | ... /usr/local/bin/isorespin.sh ... --rolling-testing | --rolling-testing-hwe | --rolling-testing-hwe-edge | --rolling-unstable | --rolling-unstable-hwe | --rolling-unstable-hwe-edge ] | ... /usr/local/bin/isorespin.sh ... -b [ GRUB | GRUB-32 | GRUB-64 | rEFInd | Linuxium ] | -g [ "" | "<kernel boot parameter> ... " ] | -s [ <size>MB | <size>GB ] | -w <directory> | ... /usr/local/bin/isorespin.sh ... --key "<repo> ... " | -r "<repo> ... " | -p "<pkg> ... " | -l "<pkg.deb> ... " | -e "<pkg> ... " | -d "<pkg> ... " | -f [ "<file> | <directory> ... " ] | ... /usr/local/bin/isorespin.sh ... -c "<cmd> ... " | -o [ "<file> | <directory> ... " ] | -t <template configuration file> | --apollo | --atom | --interactive | --debug ]
Respinng an ISO is controlled by either running the script with flags and arguments (CLI) or selection options and values (GUI) and briefly these are as follows:
The script can either be run as a local script or it can be installed by copying the script to '/usr/local/bin' where it will be accessible for all users after the script has been made executable using the 'chmod' command ('sudo chmod 755 isorespin.sh'). Depending on the options and their complexity the respinning will take quite a few minutes and the script provides updates on its progress whilst running. The respun ISO is created with a new name derived from the original ISO name and includes indicators of the options used like 'persistence' or the kernel version for example with full details being written to the log file. Once the ISO has been respun it can be written to a USB using the standard 'dd' command. The examples below illustrate the various options through scenarios and provide a basic tutorial to using the script. They are based on the script being installed to '/usr/local/bin':
The script's help is displayed using the command: isorespin.sh -h
The version of the script can either be displayed by entering: isorespin.sh -v
or it can be seen from the top of the script's 'main' menu:
or 'advanced' menu:
The script can be run using the CLI by specifying options with arguments in any order. If the script is started without any parameters it first checks to see if it can run the GUI and if so starts with the main selection menu where all required options should be selected. As seen above the GUI uses two menus with the first being a main menu of most frequently used options and an optional additional menu of the more advance options. For each option selected, a sub-menu will appear to allow the choice or value to be entered. Respinning an ISO The simplest usage is to respin an ISO which will automatically add the GRUB 32-bit bootloader allowing the respun ISO to boot on Intel Atom devices e.g.: isorespin.sh -i ubuntu-17.04-desktop-amd64.iso or by invoking the GUI:
To respin the ISO with the latest kernel the command would be: isorespin.sh -i ubuntu-17.04-desktop-amd64.iso -u or
If a specific kernel was required for example 'v4.11.6' then the '-k' option would be used: isorespin.sh -i ubuntu-17.04-desktop-amd64.iso -k v4.11.6 or
Booting the ISO on Intel Atom or and Intel Apollo Lake devices If you want to use the ISO on an Intel Atom or an Intel Apollo Lake device then simply add either the '--atom' or '--apollo' option respectively when respinning the ISO. This is further explained under the section 'Target processors' below and uses functionality explained in the next section. Finally once you have respun your ISO you need to write it to a USB which is explained under the section 'Creating a LiveUSB' with booting explained under 'Booting your respun ISO'. Adding local packages and running scripts A more complex scenario of respinning an ISO is when you want to add packages and run scripts to fix functionality like wifi/bt and audio. Due to current limitations of the official ISOs I've previously created scripts to add wifi/bt firmware and also add the ALSA UCM audio files: linuxium-install-broadcom-drivers.sh These can be incorporated when respinning an ISO. For the scripts you first add the file using the '-f' option and then execute the script using the '-c' option. When I wrote the above scripts I originally intended them to be run post installation rather than as part of respinning an ISO. As a result they produce warnings and also need to be executed in the correct directory. Rather than writing a complex '-c' parameter to run them correctly it is simpler to write a further script (which I call a 'wrapper') which controls how the script is run. These 'wrappers' can then be included as part of respinning an ISO: wrapper-linuxium-install-broadcom-drivers.sh wrapper-linuxium-install-UCM-files.sh For example the following command will respin the Ubuntu 17.04 ISO and upgrade the kernel to the latest version (which includes the RTL8723BS driver) installs the required RTL8723BS wifi/bt firmware and both adds and runs a script to include the UCM files for audio: isorespin.sh -i ubuntu-17.04-desktop-amd64.iso -u -l rtl8723bs_4.12.0_amd64.deb -f linuxium-install-UCM-files.sh -f wrapper-linuxium-install-UCM-files.sh -c wrapper-linuxium-install-UCM-files.sh
While the script is running progress updates are displayed:
until it finally completes:
producing a log file which shows how the script was run:
A similar example but respinning the daily snapshot Ubuntu 17.10 (Artful) ISO and using the GUI starts by selecting the required options:
and then entering the values starting with the ISO. When selecting the ISO a 'file manager' styled window will be presented but only files ending with a '.iso' suffix will be displayed:
For the kernel upgrade option the choice is to upgrade to the latest mainline version:
Local packages are selected using the 'file manager' which only displays '.deb' files. To allow multiple entries you will be asked after each selection is made whether a further addition is required:
Next the two scripts are added using the 'file manager':
And finally the 'advanced' menu is displayed and after selecting the option to add a command:
the command is entered as a text string:
Now that all the selected options have been entered a confirmation screen is be displayed which shows the full command as it would look if the script had been run manually:
Having selected 'yes' the script runs and displays its progress:
until it finishes:
Similarly a log file is produced that shows how the script was run:
For a more complex example of using the script see Compiling your own kernel using 'isorespin.sh'.
Adding persistence to an ISO is useful as it means that you can retain your data, installed software packages and settings between reboots. Persistence can be added as part of any ISO respinning simply by adding the '-s' option and defining the size of the storage to be permanently allocated in the ISO. As previously mentioned there is a balance between making it small and therefore resulting in a small ISO that requires resizing once booted (see below) verses a larger size and a corresponding larger ISO. The following example respins the standard Ubuntu 17.04 ISO with the latest kernel and create a 2 GB persistence partition: isorespin.sh -i ubuntu-17.04-desktop-amd64.iso -u -s 2GB Using the GUI it is created by:
As can be seen from looking at the size of the resulting ISO that it is large at around 3.8 GB but not too large to be totally impractical. Kernel boot parameters
isorespin.sh -i ubuntu-17.04-desktop-amd64.iso -g "" -g "i915.fastboot=1 fbcon=rotate:1" The default kernel boot parameters are first removed by selecting the delete option:
and the new kernel boot parameters are then added:
as text strings:
Once the script is running it will update the kernel boot parameters:
with the exact details being recorded in the log file:
Rolling kernels The need for rolling kernels is primarily to address the shortfall that existing ISO kernels typically don't have the hardware support required for the latest devices. They ship with the 'kernel of the day' whereas the latest hardware tends to require, well, the latest kernel to fully work. Ubuntu have in part addressed this through their LTS Enablement Stacks. Another alternative to get 'newer' kernels is to enable the proposed repository however there is also a pre-release and test kernel repository together with the unstable repository where mainline kernels are migrated into Ubuntu as well as the upstream mainline kernels.
I've added an option '--rolling-list' to keeping track of what new kernels are available where with options to easily incorporate them when respinning an ISO. I've termed the kernel types as release, proposed, testing and unstable to reflect the repositories they are drawn from as described above. And if it is not abundantly obvious but any kernel other than the formally released ones are not encouraged for anyone needing a stable system or anyone who is not comfortable running into occasional or even frequent breakage.
Respinning an ISO for a target processor includes the flags, packages, scripts and commands that I recommend for the ISO to work on devices and mirrors the manual invocations of: For '--atom': -l rtl8723bX_4.12.0_amd64.deb -f linuxium-install-UCM-files.sh -f wrapper-linuxium-install-UCM-files.sh -f linuxium-install-broadcom-drivers.sh -f wrapper-linuxium-install-broadcom-drivers.sh -c wrapper-linuxium-install-UCM-files.sh -c wrapper-linuxium-install-broadcom-drivers.sh
The files are automatically downloaded from the internet if they are not found as part of the command invocation and this should simplify respinning for those looking something quick and easy. The '--atom' option requires that you have the 'p7zip-full' package installed prior to running the respin script however the script will check and warn you if it is missing. The options have been included in the GUI:
Templates are similar to how the processor options of 'atom' and 'apollo' work in that a template is a list of options to be included when respinning are useful when you find yourself using the same combination of options. Typically each combination is to include a specific type of functionality. An example might be for someone with a Broadcom wifi device always having to load and move the NVRAM file to its required location. For example the required options might be: -f nvram.txt \ which can be saved in a text file, say 'wifi.tpl', with the extension '.tpl' being used just to serve as a descriptive reminder of the file's contents. This file can then be used with the new '-t' or '--template' option when respinning, for example:
Templates can also be combined. Another example might be when a specific set of packages is required such as for 'ssh' so if the template file 'ssh.tpl' contained '-p "ssh openssh.server"' then respinning with both 'wifi' and 'ssh' is as simple as:
There actually is no reason why the '--atom' option cannot be included within a template however it would make sense to call the template something meaningful e.g. 'atom-wifi.tpl'. Templates are also extremely useful for complex respins. To respin an ISO for the GPD Pocket device the current command is: isorespin.sh -i <ISO> \ Whilst this can be stored as a template to simplify things further templates can in turn contain templates so a complex respin can both be easier to build and understand. For example we could build a template for 'display' as 'gpd-display.tpl' containing: --file gpd-pocket-ubuntu-respin/display/20-intel.conf --file gpd-pocket-ubuntu-respin/display/30-monitor.conf --file gpd-pocket-ubuntu-respin/display/35-screen.conf --file gpd-pocket-ubuntu-respin/display/40-touch.conf --file gpd-pocket-ubuntu-respin/display/40-trackpoint.conf --file gpd-pocket-ubuntu-respin/display/console-setup --file gpd-pocket-ubuntu-respin/display/monitors.xml --file gpd-pocket-ubuntu-respin/display/adduser.local --file gpd-pocket-ubuntu-respin/display/90-scale --file gpd-pocket-ubuntu-respin/display/90-interface --file gpd-pocket-ubuntu-respin/display/wrapper-display.sh --command wrapper-display.sh and then similar templates for 'gpd-audio.tpl', 'gpd-fan.tpl' etc. together with a 'gpd.tpl' template containing: --template gpd-kernel.tpl --template gpd-packages.tpl --template gpd-display.tpl --template gpd-audio.tpl --template gpd-fan.tpl --template gpd-network.tpl --template gpd-power.tpl --template gpd-grub.tpl So respinning Ubuntu Bionic for the GPD Pocket becomes:
Taken to an even further level the ISO can be specified as a template e.g. 'bionic.tpl' containing '-i ubuntu-18.04-desktop-amd64.iso' So the final respin becomes:
To assist in building templates each time 'isorespin.sh' is successfully run a template file 'isorespin.tpl' is created containing the options used in respinning excluding the ISO option.
Fot the GPD Pocket example above the 'isorespin.tpl' file after respinning contains: --kernel v4.17-rc2 --erase bcmwl-kernel-source --package "xfonts-terminus thermald tlp va-driver-all vainfo libva2 i965-va-driver gstreamer1.0-libav gstreamer1.0-vaapi vlc python-gi git python gir1.2-appindicator3-0.1" --file /<path>/gpd-pocket-ubuntu-respin/display/20-intel.conf --file /<path>/gpd-pocket-ubuntu-respin/display/30-monitor.conf --file /<path>/gpd-pocket-ubuntu-respin/display/35-screen.conf --file /<path>/gpd-pocket-ubuntu-respin/display/40-touch.conf --file /<path>/gpd-pocket-ubuntu-respin/display/40-trackpoint.conf --file /<path>/gpd-pocket-ubuntu-respin/display/console-setup --file /<path>/gpd-pocket-ubuntu-respin/display/monitors.xml --file /<path>/gpd-pocket-ubuntu-respin/display/adduser.local --file /<path>/gpd-pocket-ubuntu-respin/display/90-scale --file /<path>/gpd-pocket-ubuntu-respin/display/90-interface --file /<path>/gpd-pocket-ubuntu-respin/display/wrapper-display.sh --command wrapper-display.sh --file /<path>/gpd-pocket-ubuntu-respin/audio/chtrt5645.conf --file /<path>/gpd-pocket-ubuntu-respin/audio/HiFi.conf --file /<path>/gpd-pocket-ubuntu-respin/audio/headphone-jack --file /<path>/gpd-pocket-ubuntu-respin/audio/headphone-jack.sh --file /<path>/gpd-pocket-ubuntu-respin/audio/wrapper-audio.sh --command wrapper-audio.sh --file /<path>/gpd-pocket-ubuntu-respin/fan/gpdfand --file /<path>/gpd-pocket-ubuntu-respin/fan/gpdfand.conf --file /<path>/gpd-pocket-ubuntu-respin/fan/gpdfand.py --file /<path>/gpd-pocket-ubuntu-respin/fan/gpdfand.service --file /<path>/gpd-pocket-ubuntu-respin/fan/wrapper-fan.sh --command wrapper-fan.sh --file /<path>/gpd-pocket-ubuntu-respin/network/99-local-bluetooth.rules --file /<path>/gpd-pocket-ubuntu-respin/network/brcmfmac4356-pcie.txt --file /<path>/gpd-pocket-ubuntu-respin/network/wrapper-network.sh --command wrapper-network.sh --file /<path>/gpd-pocket-ubuntu-respin/power/wrapper-power.sh --command wrapper-power.sh --grub "" --grub "i915.fastboot=1 i915.semaphores=1 fbcon=rotate:1 gpd-pocket-fan.speed_on_ac=0" where '/<path>/' is the full path to the specified file.
Besides using the template file as a base for further individual templates you can also simply recreate the last respun ISO by rerunning with the last generated template:
Interactively updating an ISO Sometimes trying to respin an ISO using complex option combinations fails as typically the consequences of running certain commands or their effect on the ISO are not fully known or easily predictable. In these circumstances respinning interactively would be easier and hence the option '--interactive'. This option simply drops you into a 'root' shell where you can manually enter commands to modify the ISO:
Simply press 'control-D' when finished to return to respinning the ISO. This option uses the 'script' command to record the interactive session so that it can be included in the log file in full if the '--debug' option is used in conjunction or manipulated to just show a summary of the commands entered for inclusion into the default log file. This command summary is also included in the 'README.isorespin' file that is added to the respun ISO. As a result 'isorespin.sh' now depends on the package 'bsdutils' being installed which should already be the case in most situations. Because 'script' makes a typescript of everything displayed on the terminal it also includes temporary progress text together with cursor movement control codes and colour control codes which may become visible depending on how the log file is viewed. This may not be ideal in every circumstance however it is a compromise believed to be worthwhile considering the functionality gained. For example respinning an ISO and first performing an ''apt update' and then installing the 'ethtool' package interactively:
the 'cat' command displays the log file created using the '--debug' option without distractions:
Because when performing the 'apt update' command various 'source' files are needed to be downloaded which result in progress text temporarily being displayed on the screen, when the command 'more' is used to display the log file it interprets the 'script' text in the log file differently and shows this colour-highlighted progress text:
Using the command 'view' to examine the log file shows all the text and all the control characters so consequently may not be the best way to view the log file:
For this particular example the summary of the '--interactive' commands that is also included in README.isorespin:
is similar to how this '--interactive' option is documented in the default log file without an additional '--debug' option:
Upgrading an ISO vs 'dist-upgrade' The difference between '--upgrade' and '--dist-upgrade' options is best described by the 'man' entry for the commands used by the two options: upgrade
dist-upgrade
To illustrate the difference we can look at respinning an ISO (Ubuntu 18.04.3) first with the '--upgrade' option together with the '--debug' option which shows that the kernel meta packages are held back:
However using the '--dist-upgrade' option with the '--debug' options shows that new kernel packages will be installed as a result of upgrading the kernel meta packages:
This example again highlights the usefulness of the '--debug' option in understanding what happens as part of respinning an ISO. Kali Metapackages
There are some restrictions/limitations. Unity isn't supported and I've found adding a GPG key to a 17.04 or 17.10 release fails. Additionally adding the 'kali-linux-full' package results in dependency issues. However it is possible to respin the recently released Ubuntu GNOME 16.04.3 and add 'kali-linux' and 'kali-linux-top10': Script '/usr/local/bin/isorespin.sh' called with '-i ubuntu-gnome-16.04.3-desktop-amd64.iso --atom -u --key adv --keyserver keyserver.ubuntu.com --recv-keys ED444FF07D8D0BF6 --repository deb http://http.kali.org/kali kali-rolling main contrib non-free -p kali-linux -p kali-linux-top10' ... Work directory 'isorespin' used ... ISO '/home/linuxium/ubuntu-gnome-16.04.3-desktop-amd64.iso' respun ... Bootloader 'GRUB' added ... Kernel updated with mainline kernel version '4.13.0-041300rc3-generic' ... Key 'adv --keyserver keyserver.ubuntu.com --recv-keys ED444FF07D8D0BF6' added ... Repository 'deb http://http.kali.org/kali kali-rolling main contrib non-free' added ... Package 'kali-linux' added ... Package 'kali-linux-top10' added ... Local package '/home/linuxium/isorespin/rtl8723bs_4.12.0_amd64.deb' added ... File '/home/linuxium/isorespin/linuxium-install-UCM-files.sh' added ... File '/home/linuxium/isorespin/wrapper-linuxium-install-UCM-files.sh' added ... File '/home/linuxium/isorespin/linuxium-install-broadcom-drivers.sh' added ... File '/home/linuxium/isorespin/wrapper-linuxium-install-broadcom-drivers.sh' added ... Command run ... # wrapper-linuxium-install-UCM-files.sh ./linuxium-install-UCM-files.sh: Extracting UCM files ... ./linuxium-install-UCM-files.sh: Installing UCM files ... ./linuxium-install-UCM-files.sh: Reloading UCM driver ... ./linuxium-install-UCM-files.sh: Installation of UCM finished # wrapper-linuxium-install-broadcom-drivers.sh ./linuxium-install-broadcom-drivers.sh: Extracting Broadcom files ... ./linuxium-install-broadcom-drivers.sh: Installing Broadcom files ... ./linuxium-install-broadcom-drivers.sh: Reloading Broadcom driver ... ./linuxium-install-broadcom-drivers.sh: Installing Broadcom bluetooth service ... Created symlink /etc/systemd/system/multi-user.target.wants/brcmbt.service, pointing to /lib/systemd/system/brcmbt.service. ./linuxium-install-broadcom-drivers.sh: Starting Broadcom bluetooth service ... Running in chroot, ignoring request. ./linuxium-install-broadcom-drivers.sh: Installation of Broadcom finished Respun ISO created as 'linuxium-v4.13-rc3-ubuntu-gnome-16.04.3-desktop-amd64.iso'. Lubuntu is also supported:
and by adding 'kali-desktop-lxde' additional LXDE packages are included (note 'Other'):
Debugging respinnning issues Most of the options don't include their interaction with the ISO when being executed either on the screen or in the log file. For example when adding the package 'ethtool' the log merely includes a line stating that the package has been added:
The '--debug' option redirects the output from executing the commands behind an option to the log file. Using the same example the complete output from installing the package is now included in the log file:
While including the output from successful option execution may be interesting the key benefit of using '--debug' is when a command run as part of an option fails. Having the full output including the actual error messages in the log file is invaluable for debugging respinning issues. Creating a LiveUSB Once your respun ISO has been created you can write it to a USB using 'dd'. For example if your USB is '/dev/sdb' then enter: dd if=linuxium-v4.12-rc6-ubuntu-17.04-desktop-amd64.iso of=/dev/sdb bs=4M Make sure you select the correct device for the USB and always check first using commands like 'df', 'blkid' or 'lsblk' to confirm. ISOs can also be written to a USB using 'Rufus' on Windows if preferred.
Having created the USB with your respun ISO the following information may be useful when booting and running. To boot your device select the USB's UEFI partition from the device's boot menu:
Normally you will then see a standard GRUB menu:
If the 'rEFInd' boot manger was installed (either through selection or automatically due to persistence) the following screen will be displayed for 64-bit bootloader devices:
otherwise for 32-bit bootloader devices the normal the GRUB menu screen is displayed and after selection a black screen with the following message is briefly displayed: error: no suitable video mode found. Booting in blind mode before the normal Ubuntu splash screen appears and the device fully boots. This 'error' can safely be ignored.
Bluetooth issues On booting if bluetooth fails to work automatically and the firmware was installed using one of my scripts then the service can be manually started with the command: sudo systemctl start rtl8723bsbt.service or sudo systemctl start brcmbt.service depending on device's chip. If bluetooth is always required then the command could be included in '/etc/rc.local' to avoid this step. Note that this uses 'systemd' so earlier ISO releases without 'systemd' cannot use my scripts to provide bluetooth. Resizing the persistence partition Once booted use the 'gparted' command to resize the persistence partition. You will initially be prompted to fix the GPT to use all the available space so click 'Fix'
and then continue with the resizing:
NVRAM sync issues Sometimes after installing your device only boots to a black screen. Typically this happens when the NVRAM and ESP are out of sync. This can be easily fixed by performing the following: 1. Start with the device switched off. 2. Connect your LiveUSB. 3. Power on the device and press the relevant function key or key sequence to boot from the LiveUSB. 4. Open a terminal windows and enter:
5. If the 'efibootmgr' is not installed enter:
6. Next remove any boot entries that may have been created through the earlier installs by entering: for BOOTENTRY in 0 1 2 3 4 5 6 7 8 9 7. Now create an Ubuntu boot entry by entering:
8. Remove the LiveUSB and reboot from the newly created Ubuntu entry. Note: If you have a dual boot installation then the ESP partition may be the second partition so modify the '-p 1' in the command above to '-p 2' or to whatever the ESP partition is. Likewise for some devices the eMMC is '/dev/mmcblk1' and not '/dev/mmcblk0' so again modify the command as appropriate. If your device uses a 32-bootloader then use 'bootia32.efi' rather than 'grubx64.efi' in the command. It also sometimes doesn't work first time and requires all the steps to be repeated which should then fix the issue.
When installing respun Ubuntu or similar distros on Intel Apollo devices using the '--apollo' option (or '-b Linuxium') one issue that might be encountered is where the EFI partition isn't large enough to store the bootable EFI file. Some Windows installations only create a 60MB partition which after installing the Windows EFI files leaves only around 30MB free. With the later Linux kernel releases the size and number of modules have increased and the generated bootable EFI file is now quite large (over 50MB) and if there is insufficient space for it the resultant installation will not boot. The solution is to increase the size of the EFI partition by following the instructions posted here. Additional information regarding the script Minimizing repeated downloads The rEFInd boot manager (http://www.rodsbooks.com/refind) can be downloaded from https://sourceforge.net/projects/refind/files into the same directory as the script is run from to prevent unnecessary repeated downloads if this is a concern and will make processing quicker. Avoiding new windows opening when respinning To prevent the file manager opening a window each time the script mounts a temporary file system I have run the command 'gsettings set org.gnome.desktop.media-handling automount-open false' first on my system. Lock file
Permissions If when running the script you get the error: bash: ./isorespin.sh: Permission denied it means that the script needs to be made executable which can be achieved using the 'chmod' command ('sudo chmod 755 isorespin.sh'). Restrictions You cannot respin an ISO on an OS that doesn't support 'systemd' if you want to use either the '--apollo' or the '-b Linuxium' options. Also you cannot respin an ISO if it doesn't support 'systemd' when using the '--atom', '--apollo' or '-b Linuxium' options: linuxium@LINUXIUMONE:~$ isorespin.sh -i ubuntu-14.04.5-desktop-amd64.iso --atom Extracting ISO ... Parallel unsquashfs: Using 4 processors 166333 inodes (175651 blocks) to write
created 16104 directories created 60921 symlinks created 82 devices created 0 fifos /usr/local/bin/isorespin.sh: The '--atom' option is only compatible with an ISO that uses 'systemd'. linuxium@LINUXIUMONE:~$ You cannot respin an ISO that is EOL (End Of Life): linuxium@LINUXIUMONE:~$ isorespin.sh -i ubuntu-17.04-desktop-amd64.iso --atom Extracting ISO ... /usr/local/bin/isorespin.sh: ISO is EOL. linuxium@LINUXIUMONE:~$ You cannot run the script on a 32-bit OS: linuxium@LINUXIUMONE:~$ isorespin.sh -i ubuntu-17.10.1-desktop-amd64.iso --apollo /usr/local/bin/isorespin.sh: This script can only be run on a 64-bit (amd64 or x86_64) OS. linuxium@LINUXIUMONE:~$ Running the script on Windows First download and install Oracle's VirtualBox on Windows and then create a Linux VM from a standard Ubuntu 64-bit desktop ISO and install to a VDI of fixed size (minimum 20GB). Start the new Ubuntu VM and install 'Oracle VM VirtualBox Extension Pack'. You can then download my 'isorespin.sh' script to respin the Ubuntu-based ISO of choice. By installing the extension pack you will also be able to write the respun ISO to a USB using 'dd' from within the Ubuntu VM. Unfortunately 'Bash on Ubuntu on Windows' using 'Windows Subsystem for Linux' does not support 'loop' devices which are required by my script so an Ubuntu VM is the only working alternative at this time. Running the script on Arch Linux Running the script on Arch Linux requires a modified PATH. The simplest way is to run the script as follows: PATH=/usr/sbin:/sbin:/bin:$PATH ./isorespin.sh Additionally to install the required packages it may be necessary to run:
or similar depending on which packages are missing from you environment. Miscellaneous issues not directly related to the script The Linux mainline kernel It is worth noting that certain releases of the mainline kernel include specific core functionality: v4.9 includes the eMMC v5.0 driver required for accessing the internal storage in many devices. v4.11 includes the HDMI audio driver. v4.12 includes the RTL8723BS driver although you will still need the wifi/bt firmware. Kernel freezes Well known and well documented without a permanent fix or so it seems. Kernels after v3.16 seem to include something that caused them to randomly freeze on Intel Atom devices and then the whole system hangs. Subsequently an accepted workaround was recommended to limit the processor (CPU) to a certain power state or 'C-state' and if freezes are encountered then to pass 'intel_idle.max_cstate=1' as a boot parameter. Later kernels have included patches and the current state seems to be reliable enough to ignore the workaround. If however freezes still occur the easiest way to implement the workaround on an installed system is to edit the file '/boot/grub/grub.cfg' and modify to look like: GRUB_CMDLINE_LINUX_DEFAULT="intel_idle.max_cstate=1" Alternatively the following command can be entered:
followed by:
and then a reboot as the change only needs to be made once typically following installation. Micro SD card issues Whilst micro SD cards have worked on Intel Atom Bay Trail devices it is only since the v4.7.2 kernel that Intel Atom Cherry Trail devices have had any form of success. The typical error encountered is: mmc1: error -110 whilst initialising SD card mmc1: card never left busy state and although most Class 10 and below cards from any manufacturer except Sandisk work now without problem some UHS cards still fail. I've found Samsung UHS Speed Class 3 and UHS Speed Class 1 work whereas similar Sandisk cards fail crashing the device sometimes when inserting or removing the card. No sound from headphones or internal speakers It may be necessary to first use the speaker controls to select the audio output before sound works. For audio on Lubuntu this will also require installing the package 'pavucontrol':
and then using it to select the audio output e.g. HDMI. Unfortunately some devices still require additional audio drivers or specific device quirks that have not been incorporated into the mainline kernel so sound may only work over HDMI and not through internal speakers or via the headphone jack even though the UCM files have been added. This is part of ongoing Linux development and future kernel releases hopefully will include the drivers required for currently non-working devices.
Unfortunately the standard Ubuntu ISO requires an internet connection when installing on devices with a 32-bit boot loader otherwise the following error is encountered:
My script solves this for Ubuntu ISOs as it will now add the required GRUB packages allowing the installation to successfully complete. However other Ubuntu ISOs including the Ubuntu flavours and distros based on Ubuntu (such as Linux Mint) etc. their installation without the internet on 32-bit devices is with varying success. In part it depends on the original ISO installation capability on 64-bit devices without the internet. For example as Lubuntu 17.04 cannot be installed on 64-bit devices without internet as the ISO does not contain '/pool' with required packages so likewise after respinning its installation on 32-bit devices is not possible. However Lubuntu 16.04.2 can be installed on both 64-bit and 32-bit devices after respinning (see http://cdimage.ubuntu.com/lubuntu/releases/16.04.2/release/lubuntu-16.04.2-desktop-amd64.list and http://cdimage.ubuntu.com/lubuntu/releases/17.04/release/lubuntu-17.04-desktop-amd64.list for detailed package information). Also for non-Ubuntu ISOs it depends on the availability of archived package versions as some ISOs are created with earlier GRUB package versions to those currently available. For example with Elementary OS the earlier packages are not available and it is not known where (or if) an archive copy is maintained so installing without the internet on 32-bit devices is not possible. Suspend/Hibernate/Sleep issues
Brightness issues Unfortunately as I don't have a tablet I cannot advise on the various screen related issues some users experience using Ubuntu. The best command appears to be 'xrandr' although its use is device specific. Many people have commented in previous posts with their solutions and I've included some of these below. Most brightness suggestions include: xrandr --output [device_name] --brightness floating_pvalue (0 <= x <= 1.0) where you can determine your device by entering: xrandr -q | grep "connected" with the primary one being your device. For example: xrandr --output DSI-1 --brightness .${BRIGHTNESS} where the variable BRIGHTNESS can take a value between 3 and 9.
xinput set-prop <Device Touchscreen> 'Coordinate Transformation Matrix' 0 1 0 -1 0 1 0 0 1 and
xinput set-prop 'Goodix Capacitive TouchScreen' 'Coordinate Transformation Matrix' 0 1 0 -1 0 1 0 0 1 Also others have reported that screen rotation during boot works with 'fbcon=rotate:1'. Touchscreen issues These seem to be related to rotation issues and another example of a solution includes: xinput set-prop "Silead GSLx680 Touchscreen" "Coordinate Transformation Matrix" 1 0 0 0 -1 1 0 0 1 which can also be set when matching InputClass section in 'xorg.conf' with: Option "TransformationMatrix" "1 0 0 0 -1 1 0 0 1" Installation on Intel Apollo Lake Devices On Intel Apollo Lake devices you will need to include either the '--apollo' or '-b Linuxium' or '-b rEFInd' option when respinning the ISO to enable booting having first ensured sufficient space is available in the EFI partitions (see Resize EFI partition). Note that the '-b Linuxium' option requires that the package 'bintuils' is installed so if in doubt use the '--apollo' or include the package as another option (i.e. use '-b Linuxium -p binutils'). Reporting issues Comments are welcome but when discussing an issue please include the name of your device and use 'pastebinit' or similar to post a URL to a copy of the output from 'dmesg' (which is basically a log of kernel messages). To use the 'pastebinit' command (see https://help.ubuntu.com/community/Pastebinit) first install the command by entering 'sudo apt-get install -y pastebinit' and then to share the kernel messages log enter 'dmesg | pastebinit'. This will paste a copy of the output from 'dmesg' to Ubuntu's Pastebin and provide a URL to access it. So when reporting an issue please include:
Donate Please donate if you find the script useful using the following link http://goo.gl/nXWSGf as everything helps with development costs. |
How-Tos >
