Difference between revisions of "Installing/Creating Bootable USB"

From GalliumOS Wiki
Jump to: navigation, search
(remove dead youtube link)
 
(32 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 
Creating bootable GalliumOS media is very similar to other Linux distributions. Unfortunately, that doesn't mean it's easy. The goal of this guide is to make it as straightforward as possible.
 
Creating bootable GalliumOS media is very similar to other Linux distributions. Unfortunately, that doesn't mean it's easy. The goal of this guide is to make it as straightforward as possible.
  
== On Linux ==
+
== On Windows, macOS (OS X), and Linux (using Etcher) ==
  
First, you need to download the GalliumOS iso for your Chromebook.
+
Etcher is an excellent tool for writing the ISOs to bootable USBs because it is fast, easy to use, and it automatically verifies the integrity of the image after writing it.
  
Once the iso is finished downloading (you MUST wait for it to finish), open up your favourite Terminal emulator.
+
Before you get started, '''download the correct version of GalliumOS for your device''' from https://galliumos.org/download If you don't know which version you need, check out the [[Hardware Compatibility]] page.
  
cd to the place where you downloaded the iso. It's probably ~/Downloads.
+
Also, '''download the correct version of Etcher for your operating system''' from http://www.etcher.io/
 +
Once you've downloaded both and installed Etcher, proceed with the guide.
  
<code>cd ~/Downloads</code>
+
# '''Launch Etcher.''' It may ask you for your password. Etcher requires root (or Administrator) permissions to get write access to the raw devices.
 +
# '''Plug your flash drive in''' to your computer
 +
# '''Click on "Select Image"''' in Etcher
 +
# '''Select the GalliumOS iso''' by navigating through the files and folders in your filesystem
 +
# '''Select your flash drive''' in Etcher. If it is the only one connected to your computer, it should select it automatically. Make certain you choose the right one. Everything on the selected drive will be permanently erased.
 +
# '''Start the flash''' by clicking "Flash!" in Etcher. It may take quite a while, depending on the speed of your flash drive and your computer.
 +
# '''Verify the write'''. After flashing, Etcher will automatically verify that the write was successful. '''Important!''' If you're on macOS, a dialog stating that the disk you inserted was not readable may appear. Make sure you click on "Ignore", as any other button may damage the GalliumOS Installer.
 +
# '''Close Etcher''' after you see the "Flash Complete!" confirmation screen. '''It is now safe to remove your drive and install GalliumOS!'''
  
Plug in your USB device, identify it, and unmount it. This is a little tricky. You can use <code>lsblk</code> to get a list of storage devices attatched to your system. Try to find out which one is your USB flash drive. It is very important to not get this wrong, as it could cause catastrophic data loss. Once you've figured it out, make sure the USB flash drive is unmounted.
+
'''If you are unable to boot your ChromeOS device using your new USB media, see [[Installing/Creating Bootable USB#Troubleshooting|Troubleshooting]], below.'''
  
<code>sudo umount -f /dev/sdb1</code>
+
== On ChromeOS or Linux (Traditional) ==
  
Be sure to replace sdb1 with the actual partition name as listed in lsblk. Next, use dd to copy the ISO to the USB flash drive.
+
<div style="padding:0.2em; background-color:#ffffcc; border:1px solid #cccc88">
 +
* We recommend '''dd''' or '''cp''' (see below)
 +
* '''Do not use the ChromeOS Recovery Tool to write ISOs'''
 +
</div>
  
<code>dd bs=1M if=galliumos.iso of=/dev/sdb</code>
+
# First, you need to download the GalliumOS iso for your Chromebook.
 +
# Once the iso is finished downloading (you MUST wait for it to finish), open up your favourite Terminal emulator.
 +
# cd to the place where you downloaded the iso. It's probably ~/Downloads.
 +
# <code>cd ~/Downloads</code>
 +
#Plug in your USB device, identify it, and unmount it. This is a little tricky. You can use <code>lsblk</code> to get a list of storage devices attached to your system. Try to find out which one is your USB flash drive. It is very important to not get this wrong, as it could cause catastrophic data loss. Once you've figured it out, make sure the USB flash drive is unmounted.
 +
# <code>sudo umount -f /dev/sdb1</code>
 +
# Be sure to replace sdb1 with the actual partition name as listed in lsblk. Next, use dd to copy the ISO to the USB flash drive.
 +
# <code>sudo dd bs=1M if=galliumos.iso of=/dev/sdb ; sync</code>
 +
#Be sure to replace galliumos.iso with the filename of the iso you want to write. Usually typing "galliumos" and hitting tab will autocomplete it for you. Also be sure to replace <code>sdb</code> with the actual device as listed in <code>lsblk</code>. Make sure to write to the DEVICE and NOT the partition. This process can take a long time depending on the speed of your flash drive, USB connection, and hard drive. Be patient. Once the prompt comes back, the ISO should be written.
  
Be sure to replace galliumos.iso with the filename of the iso you want to write. Usually typing "galliumos" and hitting tab will autocomplete it for you. Also be sure to replace sdb with the actual device as listed in lsblk. Make sure to write to the DEVICE and NOT the partition. This process can take a long time depending on the speed of your flash drive, USB connection, and hard drive. Be patient. Once the prompt comes back, the ISO should be written. If you're getting errors, try adding sudo to the beginning of the command. Before you unplug your flash drive, be sure to run <code>sync</code>
+
'''If you are unable to boot your ChromeOS device using your new USB media, see [[Installing/Creating Bootable USB#Troubleshooting|Troubleshooting]], below.'''
  
 +
== On macOS (OS X) (Traditional) ==
  
== On Mac OS X ==
+
# '''Download the GalliumOS ISO''' for your ChromeOS device: https://galliumos.org/download
 
 
# '''Download the GalliumOS ISO''' for your ChromeOS device: https://galliumos.org/download.html
 
 
# '''Insert USB media''' into Mac OS X machine
 
# '''Insert USB media''' into Mac OS X machine
 
# '''Carefully determine device path''' for newly inserted USB media from a Terminal.app window<div style="background-color:#404040;color:white;padding:0.1em 0.5em;width:40em;font-family:monospace;font-size:1.2em"><span style="color:#00ff00">bash$ </span>diskutil list</div>The device path will be something like <code>/dev/diskN</code>. Replace <code>N</code> in all steps below with the correct disk number.<div style="background-color:#fff8f8;border:1px solid #cc0000;padding:0.2em 0.5em;width:80%"><span style="font-size:1.2em;font-weight:bold;color:#cc0000;margin:0 0.3em;padding:0.1em 0.3em;background-color:#ffdddd">&#9889;</span>It is '''''extremely''''' important to determine the correct device path for your USB media in this step. Using the wrong device path in the following steps could damage your OS X install and cause irreparable data loss!</div>
 
# '''Carefully determine device path''' for newly inserted USB media from a Terminal.app window<div style="background-color:#404040;color:white;padding:0.1em 0.5em;width:40em;font-family:monospace;font-size:1.2em"><span style="color:#00ff00">bash$ </span>diskutil list</div>The device path will be something like <code>/dev/diskN</code>. Replace <code>N</code> in all steps below with the correct disk number.<div style="background-color:#fff8f8;border:1px solid #cc0000;padding:0.2em 0.5em;width:80%"><span style="font-size:1.2em;font-weight:bold;color:#cc0000;margin:0 0.3em;padding:0.1em 0.3em;background-color:#ffdddd">&#9889;</span>It is '''''extremely''''' important to determine the correct device path for your USB media in this step. Using the wrong device path in the following steps could damage your OS X install and cause irreparable data loss!</div>
 
# '''Unmount USB media''' from OS X<br><div style="background-color:#404040;color:white;padding:0.1em 0.5em;width:40em;font-family:monospace;font-size:1.2em"><span style="color:#00ff00">bash$ </span>diskutil unmountDisk /dev/disk<span style="color:yellow">N</span></div>
 
# '''Unmount USB media''' from OS X<br><div style="background-color:#404040;color:white;padding:0.1em 0.5em;width:40em;font-family:monospace;font-size:1.2em"><span style="color:#00ff00">bash$ </span>diskutil unmountDisk /dev/disk<span style="color:yellow">N</span></div>
# '''Copy the ISO''' to USB media<br><div style="background-color:#404040;color:white;padding:0.1em 0.5em;width:40em;font-family:monospace;font-size:1.2em"><span style="color:#00ff00">bash$ </span>sudo dd if=<span style="color:yellow">./galliumos.iso</span> of=/dev/<span style="color:#00ff00">r</span>disk<span style="color:yellow">N</span> bs=1m</div><div style="background-color:#fffff0;border:1px solid #c0c044;padding:0.2em 0.5em;margin:0.5em 0 0 0;width:80%"><span style="font-size:1.2em;font-weight:bold;color:#888822;margin:0 0.3em;padding:0.1em 0.25em;background-color:#ffffcc">&#x2605;</span>Be sure to use the <code>rdisk</code> device name in the output file (<code>of=</code> parameter), and use the correct path and filename for the <code>galliumos.iso</code> file which you downloaded in step 1.</div>
+
# '''Copy the ISO''' to USB media (<code>dd</code> works too, but <code>cp</code> is simpler and more familiar)<br><div style="background-color:#404040;color:white;padding:0.1em 0.5em;width:40em;font-family:monospace;font-size:1.2em"><span style="color:#00ff00">bash$ </span>sudo cp -X <span style="color:yellow">./galliumos.iso</span> /dev/<span style="color:#00ff00">r</span>disk<span style="color:yellow">N</span></div><div style="background-color:#fffff0;border:1px solid #c0c044;padding:0.2em 0.5em;margin:0.5em 0 0 0;width:80%"><span style="font-size:1.2em;font-weight:bold;color:#888822;margin:0 0.3em;padding:0.1em 0.25em;background-color:#ffffcc">&#x2605;</span>Be sure to use the correct path and filename for the <code>galliumos.iso</code> file downloaded in step&nbsp;1, and to use the <code>rdisk</code> device name as the copy destination. The <code>-X</code> option is required to strip any extended attributes that are added by web browsers to downloaded files.</div>
 
# '''Eject USB media''' from OS X<br><div style="background-color:#404040;color:white;padding:0.1em 0.5em;width:40em;font-family:monospace;font-size:1.2em"><span style="color:#00ff00">bash$ </span>diskutil eject /dev/disk<span style="color:yellow">N</span></div>
 
# '''Eject USB media''' from OS X<br><div style="background-color:#404040;color:white;padding:0.1em 0.5em;width:40em;font-family:monospace;font-size:1.2em"><span style="color:#00ff00">bash$ </span>diskutil eject /dev/disk<span style="color:yellow">N</span></div>
 
# '''Remove USB media''' from Mac OS X machine, it's now ready for your ChromeOS device
 
# '''Remove USB media''' from Mac OS X machine, it's now ready for your ChromeOS device
  
== On Windows ==
+
'''If you are unable to boot your ChromeOS device using your new USB media, see [[Installing/Creating Bootable USB#Troubleshooting|Troubleshooting]], below.'''
 +
 
 +
== On Windows (Traditional) ==
 +
 
 +
<div style="padding:0.2em; background-color:#ffffcc; border:1px solid #cccc88">
 +
* We recommend '''Etcher''' (see above) or '''Win32DiskImager''' (see below)
 +
* '''Rufus''' is also fine, but '''be sure to select <code>"Write in DD-Image mode"</code>'''
 +
* '''Do not use UNetbootin'''
 +
* '''Do not use YUMI'''
 +
* '''Do not use ISO to USB'''
 +
</div>
  
<embedvideo service="youtube" dimensions="640x480">https://www.youtube.com/watch?v=UmuWZXtkBaE</embedvideo>
+
Before you get started, '''download the correct version of GalliumOS for your device''' from https://galliumos.org/download If you don't know which version you need, check out the [[Hardware Compatibility]] page.
If the video is too fast for you, read the instructions!
 
  
First, download the correct iso for your device.
+
Also, '''download and install Win32DiskImager''' from [[http://sourceforge.net/projects/win32diskimager/files/latest/download SourceForge]]. If you already have it, just open it up.
  
Wait for the download to finish completely before proceeding.
+
# '''Launch Win32DiskImager'''
 +
# '''Plug in your USB device''' and identify it's drive letter.
 +
# '''Click the folder button''' next to the empty box on Win32DiskImager.
 +
# '''Change the file type''' from Disk Images (.img) to *.*.
 +
# '''Select the GalliumOS iso''' by navigating through the files and folders on your filesystem.
 +
# '''Select the letter of your USB drive''' from the dropdown in Win32DiskImager.
 +
# '''Click the Write button''' on Win32DiskImager.
 +
# '''Confirm the write''' if prompted to overwrite or corrupt of physical device.
 +
# '''Wait''' for it to finish... It may take a while.
 +
# '''Click OK''' when you see the Write Successful popup.
 +
# '''Eject your USB drive''' before unplugging it.
  
Also download, install, and open Win32DiskImager from [[http://sourceforge.net/projects/win32diskimager/files/latest/download SourceForge]]. If you already have it, just open it up.
+
'''If you are unable to boot your ChromeOS device using your new USB media, see [[Installing/Creating Bootable USB#Troubleshooting|Troubleshooting]], below.'''
  
Plug in your USB device and identify it's drive letter.
+
== Troubleshooting ==
  
Click the folder button next to the empty box on Win32DiskImager.
+
Creating installation media is (by far!) the most error-prone step to installing GalliumOS.
  
Change the file type from Disk Images (.img) to *.*.
+
There are many things that can go wrong. Some errors are immediately obvious (won't boot), others can be very surprising (installer crash, IO errors). If you're having trouble, consider this list of possibilities:
  
Use the file dialog to navigate to and open the GalliumOS iso from your Downloads folder (or wherever else it may have saved).
+
=== (Very) Common Problems ===
 +
* '''Mistaken write''': Human error happens! Please reread the instructions very carefully -- make sure you're writing to the correct device, and to the correct device file (which is different from the device file in other commands).
 +
* '''Corrupt write''': We frequently see corrupt writes to USB/SD media even when all steps are followed correctly. Sometimes the second or third try "just works", but confirm the MD5 checksum first.
 +
* '''Bad USB/SD media''': These devices aren't known for their reliability. Try a different USB drive or SD card if you are able.
  
Select the letter of your USB drive from the dropdown in Win32DiskImager.
+
=== Less-Common Problems ===
 +
* '''Corrupt image download''': Compare the MD5 checksum for your download to the the published checksum. Replace <code>galliumos.iso</code> with the name of the file you downloaded, of course:
 +
** Linux: <code>md5sum ./galliumos.iso</code>
 +
** macOS: <code>md5 ./galliumos.iso</code>
 +
** Windows: https://www.microsoft.com/en-us/download/details.aspx?id=11533
 +
* '''Wrong USB port''': Some models and firmwares only boot from USB2.0 (black) ports, not USB3.0 (blue) ports. This is only a boot problem -- writing should work to either.
 +
* '''Bad image''': Sometimes we make bad nightly images! It's rare, but it has happened. Please let us know if you run into this problem. The ISOs linked from the [https://galliumos.org/download GalliumOS download page] are well-tested, so try one of those instead.
  
Click the Write button on Win32DiskImager.
+
=== Testing your USB drive and write ===
  
If prompted to confirm overwrite or corruption of physical device, click Yes.
+
You can verify your image, as-written to USB or SD media. This is often different from the image saved to the ISO file, which always indicates a problem!
  
Wait for it to finish... It may take a while.
+
The steps are a bit more complicated, and sometimes need to be repeated more than once to identify intermittently-failing USB/SD storage media:
  
When you see the Write Successful popup, click OK.
+
    # Verify the ISO image, as-written to USB or SD media
 +
    #
 +
    # Replace "galliumos.iso" with the path to your ISO file
 +
    # Replace "/dev/sdb" with the device path of your USD or SD media.
 +
    #  (check with "lsblk" and use the disk device only, not a partition device)
 +
    #
 +
    # Visit our support channel on IRC or Reddit for help with any of these steps!
 +
    #
 +
    ISO_SIZE="$(stat -c '%s' galliumos.iso)"
 +
    ISO_MEDIA="/dev/sdb"
 +
    sudo head -c "$ISO_SIZE" "$ISO_MEDIA" | md5sum
  
Eject your USB drive before unplugging it.
+
This should return an MD5 result which matches the published value, and also matches the results of the check of the ISO file itself (described above).
  
== On ChromeOS ==
+
Additionally, the GalliumOS ISO should boot any x86 computer. This is a safe test -- booting from the ISO launches a "Live" demo environment, which does not (automatically) attempt to install any software. This will only identify failed writes that impact booting, of course.
  
ChromeOS is very similar to Linux, but not identical. I will write a proper guide as soon as I have access to a Chromebook (that I haven't installed GalliumOS on :P)
+
If all else fails, you might have better luck using chrx to install GalliumOS in a dual-boot config, which downloads directly from the GalliumOS servers, and does not require any installation media.

Latest revision as of 13:27, 10 January 2022

Creating bootable GalliumOS media is very similar to other Linux distributions. Unfortunately, that doesn't mean it's easy. The goal of this guide is to make it as straightforward as possible.

On Windows, macOS (OS X), and Linux (using Etcher)

Etcher is an excellent tool for writing the ISOs to bootable USBs because it is fast, easy to use, and it automatically verifies the integrity of the image after writing it.

Before you get started, download the correct version of GalliumOS for your device from https://galliumos.org/download If you don't know which version you need, check out the Hardware Compatibility page.

Also, download the correct version of Etcher for your operating system from http://www.etcher.io/ Once you've downloaded both and installed Etcher, proceed with the guide.

  1. Launch Etcher. It may ask you for your password. Etcher requires root (or Administrator) permissions to get write access to the raw devices.
  2. Plug your flash drive in to your computer
  3. Click on "Select Image" in Etcher
  4. Select the GalliumOS iso by navigating through the files and folders in your filesystem
  5. Select your flash drive in Etcher. If it is the only one connected to your computer, it should select it automatically. Make certain you choose the right one. Everything on the selected drive will be permanently erased.
  6. Start the flash by clicking "Flash!" in Etcher. It may take quite a while, depending on the speed of your flash drive and your computer.
  7. Verify the write. After flashing, Etcher will automatically verify that the write was successful. Important! If you're on macOS, a dialog stating that the disk you inserted was not readable may appear. Make sure you click on "Ignore", as any other button may damage the GalliumOS Installer.
  8. Close Etcher after you see the "Flash Complete!" confirmation screen. It is now safe to remove your drive and install GalliumOS!

If you are unable to boot your ChromeOS device using your new USB media, see Troubleshooting, below.

On ChromeOS or Linux (Traditional)

  • We recommend dd or cp (see below)
  • Do not use the ChromeOS Recovery Tool to write ISOs
  1. First, you need to download the GalliumOS iso for your Chromebook.
  2. Once the iso is finished downloading (you MUST wait for it to finish), open up your favourite Terminal emulator.
  3. cd to the place where you downloaded the iso. It's probably ~/Downloads.
  4. cd ~/Downloads
  5. Plug in your USB device, identify it, and unmount it. This is a little tricky. You can use lsblk to get a list of storage devices attached to your system. Try to find out which one is your USB flash drive. It is very important to not get this wrong, as it could cause catastrophic data loss. Once you've figured it out, make sure the USB flash drive is unmounted.
  6. sudo umount -f /dev/sdb1
  7. Be sure to replace sdb1 with the actual partition name as listed in lsblk. Next, use dd to copy the ISO to the USB flash drive.
  8. sudo dd bs=1M if=galliumos.iso of=/dev/sdb ; sync
  9. Be sure to replace galliumos.iso with the filename of the iso you want to write. Usually typing "galliumos" and hitting tab will autocomplete it for you. Also be sure to replace sdb with the actual device as listed in lsblk. Make sure to write to the DEVICE and NOT the partition. This process can take a long time depending on the speed of your flash drive, USB connection, and hard drive. Be patient. Once the prompt comes back, the ISO should be written.

If you are unable to boot your ChromeOS device using your new USB media, see Troubleshooting, below.

On macOS (OS X) (Traditional)

  1. Download the GalliumOS ISO for your ChromeOS device: https://galliumos.org/download
  2. Insert USB media into Mac OS X machine
  3. Carefully determine device path for newly inserted USB media from a Terminal.app window
    bash$ diskutil list
    The device path will be something like /dev/diskN. Replace N in all steps below with the correct disk number.
    It is extremely important to determine the correct device path for your USB media in this step. Using the wrong device path in the following steps could damage your OS X install and cause irreparable data loss!
  4. Unmount USB media from OS X
    bash$ diskutil unmountDisk /dev/diskN
  5. Copy the ISO to USB media (dd works too, but cp is simpler and more familiar)
    bash$ sudo cp -X ./galliumos.iso /dev/rdiskN
    Be sure to use the correct path and filename for the galliumos.iso file downloaded in step 1, and to use the rdisk device name as the copy destination. The -X option is required to strip any extended attributes that are added by web browsers to downloaded files.
  6. Eject USB media from OS X
    bash$ diskutil eject /dev/diskN
  7. Remove USB media from Mac OS X machine, it's now ready for your ChromeOS device

If you are unable to boot your ChromeOS device using your new USB media, see Troubleshooting, below.

On Windows (Traditional)

  • We recommend Etcher (see above) or Win32DiskImager (see below)
  • Rufus is also fine, but be sure to select "Write in DD-Image mode"
  • Do not use UNetbootin
  • Do not use YUMI
  • Do not use ISO to USB

Before you get started, download the correct version of GalliumOS for your device from https://galliumos.org/download If you don't know which version you need, check out the Hardware Compatibility page.

Also, download and install Win32DiskImager from [SourceForge]. If you already have it, just open it up.

  1. Launch Win32DiskImager
  2. Plug in your USB device and identify it's drive letter.
  3. Click the folder button next to the empty box on Win32DiskImager.
  4. Change the file type from Disk Images (.img) to *.*.
  5. Select the GalliumOS iso by navigating through the files and folders on your filesystem.
  6. Select the letter of your USB drive from the dropdown in Win32DiskImager.
  7. Click the Write button on Win32DiskImager.
  8. Confirm the write if prompted to overwrite or corrupt of physical device.
  9. Wait for it to finish... It may take a while.
  10. Click OK when you see the Write Successful popup.
  11. Eject your USB drive before unplugging it.

If you are unable to boot your ChromeOS device using your new USB media, see Troubleshooting, below.

Troubleshooting

Creating installation media is (by far!) the most error-prone step to installing GalliumOS.

There are many things that can go wrong. Some errors are immediately obvious (won't boot), others can be very surprising (installer crash, IO errors). If you're having trouble, consider this list of possibilities:

(Very) Common Problems

  • Mistaken write: Human error happens! Please reread the instructions very carefully -- make sure you're writing to the correct device, and to the correct device file (which is different from the device file in other commands).
  • Corrupt write: We frequently see corrupt writes to USB/SD media even when all steps are followed correctly. Sometimes the second or third try "just works", but confirm the MD5 checksum first.
  • Bad USB/SD media: These devices aren't known for their reliability. Try a different USB drive or SD card if you are able.

Less-Common Problems

  • Corrupt image download: Compare the MD5 checksum for your download to the the published checksum. Replace galliumos.iso with the name of the file you downloaded, of course:
  • Wrong USB port: Some models and firmwares only boot from USB2.0 (black) ports, not USB3.0 (blue) ports. This is only a boot problem -- writing should work to either.
  • Bad image: Sometimes we make bad nightly images! It's rare, but it has happened. Please let us know if you run into this problem. The ISOs linked from the GalliumOS download page are well-tested, so try one of those instead.

Testing your USB drive and write

You can verify your image, as-written to USB or SD media. This is often different from the image saved to the ISO file, which always indicates a problem!

The steps are a bit more complicated, and sometimes need to be repeated more than once to identify intermittently-failing USB/SD storage media:

   # Verify the ISO image, as-written to USB or SD media
   #
   # Replace "galliumos.iso" with the path to your ISO file
   # Replace "/dev/sdb" with the device path of your USD or SD media.
   #   (check with "lsblk" and use the disk device only, not a partition device)
   #
   # Visit our support channel on IRC or Reddit for help with any of these steps!
   #
   ISO_SIZE="$(stat -c '%s' galliumos.iso)"
   ISO_MEDIA="/dev/sdb"
   sudo head -c "$ISO_SIZE" "$ISO_MEDIA" | md5sum

This should return an MD5 result which matches the published value, and also matches the results of the check of the ISO file itself (described above).

Additionally, the GalliumOS ISO should boot any x86 computer. This is a safe test -- booting from the ISO launches a "Live" demo environment, which does not (automatically) attempt to install any software. This will only identify failed writes that impact booting, of course.

If all else fails, you might have better luck using chrx to install GalliumOS in a dual-boot config, which downloads directly from the GalliumOS servers, and does not require any installation media.