396 lines
22 KiB
HTML
396 lines
22 KiB
HTML
<!DOCTYPE html>
|
|
<html lang="en" prefix="og: https://ogp.me/ns#">
|
|
<head>
|
|
<meta charset="utf-8"/>
|
|
<title>Web installer | Install | GrapheneOS</title>
|
|
<meta name="description" content="Web-based installer for GrapheneOS, a security and privacy focused mobile OS with Android app compatibility."/>
|
|
<meta name="theme-color" content="#212121"/>
|
|
<meta name="color-scheme" content="dark light"/>
|
|
<meta name="msapplication-TileColor" content="#ffffff"/>
|
|
<meta name="viewport" content="width=device-width, initial-scale=1"/>
|
|
<meta name="twitter:site" content="@GrapheneOS"/>
|
|
<meta name="twitter:creator" content="@GrapheneOS"/>
|
|
<meta property="og:title" content="GrapheneOS web installer"/>
|
|
<meta property="og:description" content="Web-based installer for GrapheneOS, a security and privacy focused mobile OS with Android app compatibility."/>
|
|
<meta property="og:type" content="website"/>
|
|
<meta property="og:image" content="https://grapheneos.org/opengraph.png"/>
|
|
<meta property="og:image:width" content="512"/>
|
|
<meta property="og:image:height" content="512"/>
|
|
<meta property="og:image:alt" content="GrapheneOS logo"/>
|
|
<meta property="og:site_name" content="GrapheneOS"/>
|
|
<meta property="og:url" content="https://grapheneos.org/install/web"/>
|
|
<link rel="canonical" href="https://grapheneos.org/install/web"/>
|
|
<link rel="icon" href="/favicon.ico"/>
|
|
<link rel="icon" sizes="any" type="image/svg+xml" href="/favicon.svg"/>
|
|
<link rel="mask-icon" href="{{path|/mask-icon.svg}}" color="#1a1a1a"/>
|
|
<link rel="apple-touch-icon" href="/apple-touch-icon.png"/>
|
|
{{css|/main.css}}
|
|
<link rel="manifest" href="/manifest.webmanifest"/>
|
|
<link rel="license" href="/LICENSE.txt"/>
|
|
{{js|/js/redirect.js}}
|
|
<script type="module" src="/js/fastboot/v1.1.1/fastboot.min.mjs" integrity="sha256-OXtHjW8CO7yw1L2Od6fGK7WVTCMl7Zghu24DZDNCBjI="></script>
|
|
{{js|/js/web-install.js}}
|
|
</head>
|
|
<body>
|
|
<header>
|
|
<nav id="site-menu">
|
|
<ul>
|
|
<li><a href="/"><img src="{{path|/mask-icon.svg}}" alt=""/>GrapheneOS</a></li>
|
|
<li><a href="/features">Features</a></li>
|
|
<li><a href="/install/">Install</a></li>
|
|
<li><a href="/build">Build</a></li>
|
|
<li><a href="/usage">Usage</a></li>
|
|
<li><a href="/faq">FAQ</a></li>
|
|
<li><a href="/releases">Releases</a></li>
|
|
<li><a href="/source">Source</a></li>
|
|
<li><a href="/history/">History</a></li>
|
|
<li><a href="/articles/">Articles</a></li>
|
|
<li><a href="/donate">Donate</a></li>
|
|
<li><a href="/contact">Contact</a></li>
|
|
</ul>
|
|
</nav>
|
|
</header>
|
|
<main id="web-install">
|
|
<h1><a href="#web-install">Web installer</a></h1>
|
|
|
|
<p>This is the WebUSB-based installer for GrapheneOS and is the recommended approach
|
|
for most users. The <a href="/install/cli">command-line installation guide</a> is the
|
|
more traditional approach to installing GrapheneOS.</p>
|
|
|
|
<p>If you have trouble with the installation process, ask for help on the
|
|
<a href="/contact#community">official GrapheneOS chat channel</a>. There are almost
|
|
always people around willing to help with it. Before asking for help, make an attempt
|
|
to follow the guide on your own and then ask for help with anything you get stuck
|
|
on.</p>
|
|
|
|
<nav id="table-of-contents">
|
|
<h2><a href="#table-of-contents">Table of contents</a></h2>
|
|
|
|
<ul>
|
|
<li><a href="#prerequisites">Prerequisites</a></li>
|
|
<li><a href="#enabling-oem-unlocking">Enabling OEM unlocking</a></li>
|
|
<li><a href="#flashing-as-non-root">Flashing as non-root</a></li>
|
|
<li><a href="#booting-into-the-bootloader-interface">Booting into the bootloader interface</a></li>
|
|
<li><a href="#connecting-phone">Connecting the phone</a></li>
|
|
<li><a href="#unlocking-the-bootloader">Unlocking the bootloader</a></li>
|
|
<li><a href="#obtaining-factory-images">Obtaining factory images</a></li>
|
|
<li><a href="#flashing-factory-images">Flashing factory images</a></li>
|
|
<li><a href="#locking-the-bootloader">Locking the bootloader</a></li>
|
|
<li>
|
|
<a href="#post-installation">Post-installation</a>
|
|
<ul>
|
|
<li><a href="#booting">Booting</a></li>
|
|
<li><a href="#disabling-oem-unlocking">Disabling OEM unlocking</a></li>
|
|
<li><a href="#verifying-installation">Verifying installation</a></li>
|
|
<li><a href="#replacing-grapheneos-with-the-stock-os">Replacing GrapheneOS with the stock OS</a></li>
|
|
<li><a href="#further-information">Further information</a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</nav>
|
|
|
|
<section id="prerequisites">
|
|
<h2><a href="#prerequisites">Prerequisites</a></h2>
|
|
|
|
<p>You should have at least 2GB of free memory available and 32GB of free storage
|
|
space.</p>
|
|
|
|
<p>You need a USB cable for attaching the device to a laptop or desktop. Whenever
|
|
possible, use the high quality standards compliant USB-C cable packaged with the
|
|
device. If your computer doesn't have any USB-C ports, you'll need a high quality
|
|
USB-C to USB-A cable. You should avoid using a USB hub such as the front panel on
|
|
a desktop computer case. Connect directly to a rear port on a desktop or the ports
|
|
on a laptop. Many widely distributed USB cables and hubs are broken and are the
|
|
most common source of issues for installing GrapheneOS.</p>
|
|
|
|
<p>Installing from an OS in a virtual machine is not recommended. USB passthrough
|
|
is often not reliable. To rule out these problems, install from an OS running on
|
|
bare metal. Virtual machines are also often configured to have overly limited
|
|
memory and storage space.</p>
|
|
|
|
<p>Officially supported operating systems for the web install method:</p>
|
|
|
|
<ul>
|
|
<li>Windows 10</li>
|
|
<li>Windows 11</li>
|
|
<li>macOS Catalina</li>
|
|
<li>macOS Big Sur</li>
|
|
<li>macOS Monterey</li>
|
|
<li>Arch Linux</li>
|
|
<li>Debian 10 (buster)</li>
|
|
<li>Debian 11 (bullseye)</li>
|
|
<li>Ubuntu 20.04 LTS</li>
|
|
<li>Ubuntu 22.04 LTS</li>
|
|
<li>Ubuntu 21.10</li>
|
|
<li>ChromeOS</li>
|
|
<li>GrapheneOS</li>
|
|
<li>Google Android (stock Pixel OS) and other certified Android variants</li>
|
|
</ul>
|
|
|
|
<p>Make sure your operating system is up-to-date before proceeding.</p>
|
|
|
|
<p>Officially supported browsers for the web install method:</p>
|
|
|
|
<ul>
|
|
<li>Chromium (outside Ubuntu, since they ship a broken Snap package without working WebUSB)</li>
|
|
<li>Bromite</li>
|
|
<li>Vanadium (GrapheneOS)</li>
|
|
<li>Google Chrome</li>
|
|
<li>Microsoft Edge</li>
|
|
<li>Brave</li>
|
|
</ul>
|
|
|
|
<p>Make sure your browser is up-to-date before proceeding.</p>
|
|
|
|
<p>Do not use Incognito or other private browsing modes. These modes usually
|
|
prevent the web installer from having enough storage space to extract the
|
|
downloaded release.</p>
|
|
|
|
<p>You need one of the officially supported devices. To make sure that the device can
|
|
be unlocked to install GrapheneOS, avoid carrier variants of the devices. Carrier
|
|
variants of Pixels use the same stock OS and firmware with a non-zero carrier id
|
|
flashed onto the persist partition in the factory. The carrier id activates
|
|
carrier-specific configuration in the stock OS including disabling carrier and
|
|
bootloader unlocking. The carrier may be able to remotely disable this, but their
|
|
support staff may not be aware and they probably won't do it. Get a carrier agnostic
|
|
device to avoid the risk and potential hassle. If you CAN figure out a way to unlock a
|
|
carrier device, it isn't a problem as GrapheneOS can just ignore the carrier id
|
|
and the hardware is the same.</p>
|
|
|
|
<p>It's best practice to update the device before installing GrapheneOS to have
|
|
the latest firmware for connecting the phone to the computer and performing the
|
|
early flashing process. Either way, GrapheneOS flashes the latest firmware early
|
|
in the installation process.</p>
|
|
</section>
|
|
|
|
<section id="enabling-oem-unlocking">
|
|
<h2><a href="#enabling-oem-unlocking">Enabling OEM unlocking</a></h2>
|
|
|
|
<p>OEM unlocking needs to be enabled from within the operating system.</p>
|
|
|
|
<p>Enable the developer options menu by going to Settings ➔ About phone and
|
|
repeatedly pressing the build number menu entry until developer mode is
|
|
enabled.</p>
|
|
|
|
<p>Next, go to Settings ➔ System ➔ Developer options and toggle on the 'OEM
|
|
unlocking' setting. This requires internet access on devices with Google Play
|
|
services as part of Factory Reset Protection (FRP) for anti-theft protection.</p>
|
|
</section>
|
|
|
|
<section id="flashing-as-non-root">
|
|
<h2><a href="#flashing-as-non-root">Flashing as non-root</a></h2>
|
|
|
|
<p>On traditional Linux distributions, USB devices cannot be used as non-root
|
|
without udev rules for each type of device. This is not an issue for other
|
|
platforms.</p>
|
|
|
|
<p>On Arch Linux, install the <code>android-udev</code> package. On Debian and
|
|
Ubuntu, install the <code>android-sdk-platform-tools-common</code> package.</p>
|
|
</section>
|
|
|
|
<section id="booting-into-the-bootloader-interface">
|
|
<h2><a href="#booting-into-the-bootloader-interface">Booting into the bootloader interface</a></h2>
|
|
|
|
<p>You need to boot your phone into the bootloader interface. To do this, you need
|
|
to hold the volume down button while the phone boots.</p>
|
|
|
|
<p>The easiest approach is to reboot the phone and begin holding the volume down
|
|
button until it boots up into the bootloader interface.</p>
|
|
|
|
<p>Alternatively, turn off the phone, then boot it up while holding the volume
|
|
down button during the boot process. You can either boot it with the power button
|
|
or by plugging it in as required in the next section.</p>
|
|
</section>
|
|
|
|
<section id="connecting-phone">
|
|
<h2><a href="#connecting-phone">Connecting the phone</a></h2>
|
|
|
|
<p>Connect the phone to the computer. On Linux, you'll need to do this again if
|
|
you didn't have the udev rules set up when you connected it.</p>
|
|
|
|
<p>On Windows, you need to install a driver for fastboot if you don't already have
|
|
it. No driver is needed on other operating systems. You can obtain the driver from
|
|
Windows Update which will detect it as an optional update when the device is
|
|
booted into the bootloader interface and connected to the computer. Open Windows
|
|
Update, run a check for updates and then open the "View optional updates"
|
|
interface. Install the driver for the Android bootloader interface as an optional
|
|
update.</p>
|
|
|
|
<p>An alternative approach to obtaining the Windows fastboot driver is to obtain
|
|
the <a href="https://developer.android.com/studio/run/win-usb">latest driver for
|
|
Pixels</a> from Google and then
|
|
<a href="https://developer.android.com/studio/run/oem-usb#InstallingDriver">manually
|
|
install it with the Windows Device Manager</a>.</p>
|
|
</section>
|
|
|
|
<section id="unlocking-the-bootloader">
|
|
<h2><a href="#unlocking-the-bootloader">Unlocking the bootloader</a></h2>
|
|
|
|
<p>Unlock the bootloader to allow flashing the OS and firmware:</p>
|
|
|
|
<button id="unlock-bootloader-button" disabled="">Unlock bootloader</button>
|
|
|
|
<p>The command needs to be confirmed on the device and will wipe all data. Use one
|
|
of the volume keys to switch the selection to accepting it and the power button to
|
|
confirm.</p>
|
|
|
|
<p><strong id="unlock-bootloader-status"></strong></p>
|
|
</section>
|
|
|
|
<section id="obtaining-factory-images">
|
|
<h2><a href="#obtaining-factory-images">Obtaining factory images</a></h2>
|
|
|
|
<p>You need to obtain the GrapheneOS factory images for your device to proceed with
|
|
the installation process.</p>
|
|
|
|
<p>Press the button below to start the download:</p>
|
|
|
|
<button id="download-release-button" disabled="">Download release</button>
|
|
|
|
<p id="download-release-status-container" hidden="hidden">
|
|
<strong id="download-release-status"></strong>
|
|
<br/>
|
|
<progress id="download-release-progress" hidden="hidden" max="1" value="0"></progress>
|
|
</p>
|
|
</section>
|
|
|
|
<section id="flashing-factory-images">
|
|
<h2><a href="#flashing-factory-images">Flashing factory images</a></h2>
|
|
|
|
<p>The initial install will be performed by flashing the factory images. This will
|
|
replace the existing OS installation and wipe all the existing data.</p>
|
|
|
|
<button id="flash-release-button" disabled="">Flash release</button>
|
|
|
|
|
|
<p>Wait for the flashing process to complete. It will automatically handle
|
|
flashing the firmware, rebooting into the bootloader interface, flashing the core
|
|
OS, rebooting into the userspace fastboot mode, flashing the rest of the OS and
|
|
finally rebooting back into the bootloader interface. Avoid interacting with the
|
|
device until the flashing script is finished and the device is back at the
|
|
bootloader interface. Then, proceed to <a href="#locking-the-bootloader">locking
|
|
the bootloader</a> before using the device as locking wipes the data again.</p>
|
|
|
|
<p id="flash-release-status-container" hidden="hidden">
|
|
<strong id="flash-release-status"></strong>
|
|
<br/>
|
|
|
|
<!-- These appear as part of the status, one at a time -->
|
|
<progress id="flash-release-progress" hidden="hidden" max="1" value="0"></progress>
|
|
<button id="flash-reconnect-button" hidden="hidden"><strong>Reconnect device</strong></button>
|
|
</p>
|
|
</section>
|
|
|
|
<section id="locking-the-bootloader">
|
|
<h2><a href="#locking-the-bootloader">Locking the bootloader</a></h2>
|
|
|
|
<p>Locking the bootloader is important as it enables full verified boot. It also
|
|
prevents using fastboot to flash, format or erase partitions. Verified boot will
|
|
detect modifications to any of the OS partitions and it will prevent reading any
|
|
modified / corrupted data. If changes are detected, error correction data is used
|
|
to attempt to obtain the original data at which point it's verified again which
|
|
makes verified boot robust to non-malicious corruption.</p>
|
|
|
|
<p>In the bootloader interface, set it to locked:</p>
|
|
|
|
<button id="lock-bootloader-button" disabled="">Lock bootloader</button>
|
|
|
|
<p>The command needs to be confirmed on the device and will wipe all data. Use one
|
|
of the volume buttons to switch the selection to accepting it and the power button
|
|
to confirm.</p>
|
|
|
|
<p><strong id="lock-bootloader-status"></strong></p>
|
|
</section>
|
|
|
|
<section id="post-installation">
|
|
<h2><a href="#post-installation">Post-installation</a></h2>
|
|
|
|
<section id="booting">
|
|
<h3><a href="#booting">Booting</a></h3>
|
|
|
|
<p>You've now successfully installed GrapheneOS and can boot it. Pressing the
|
|
power button with the default Start option selected in the bootloader
|
|
interface will boot the OS.</p>
|
|
</section>
|
|
|
|
<section id="disabling-oem-unlocking">
|
|
<h3><a href="#disabling-oem-unlocking">Disabling OEM unlocking</a></h3>
|
|
|
|
<p>OEM unlocking can be disabled again in the developer settings menu within the
|
|
operating system after booting it up again.</p>
|
|
|
|
<p>After disabling OEM unlocking, we recommend disabling developer options as
|
|
a whole for a device that's not being used for app or OS development.</p>
|
|
</section>
|
|
|
|
<section id="verifying-installation">
|
|
<h3><a href="#verifying-installation">Verifying installation</a></h3>
|
|
|
|
<p>Verified boot authenticates and validates the firmware images and OS from the
|
|
hardware root of trust. Since GrapheneOS supports full verified boot, the OS images
|
|
are entirely verified. However, it's possible that the computer you used to flash the
|
|
OS was compromised, leading to flashing a malicious verified boot public key and
|
|
images. To detect this kind of attack, you can use the Auditor app included in
|
|
GrapheneOS in the Auditee mode and verify it with another Android device in the
|
|
Auditor mode.</p>
|
|
|
|
<p>The Auditor app works best once it's already paired with a device and has
|
|
pinned a persistent hardware-backed key and the attestation certificate chain.
|
|
However, it can still provide a bit of security for the initial verification
|
|
via the attestation root. Ideally, you should also do this before connecting
|
|
the device to the network, so an attacker can't proxy to another device (which
|
|
stops being possible after the initial verification). Further protection
|
|
against proxying the initial pairing will be provided in the future via
|
|
optional support for ID attestation to include the serial number in the
|
|
hardware verified information to allow checking against the one on the box /
|
|
displayed in the bootloader. See the <a href="https://attestation.app/tutorial">Auditor tutorial</a>
|
|
for a guide.</p>
|
|
|
|
<p>After the initial verification, which results in pairing, performing verification
|
|
again between the same Auditor and Auditee (as long as the app data hasn't been
|
|
cleared) will provide strong validation of the identity and integrity of the
|
|
device. That makes it best to get the pairing done right after installation. You can
|
|
also consider setting up the optional remote attestation service.</p>
|
|
</section>
|
|
|
|
<section id="replacing-grapheneos-with-the-stock-os">
|
|
<h3><a href="#replacing-grapheneos-with-the-stock-os">Replacing GrapheneOS with the stock OS</a></h3>
|
|
|
|
<p>Installation of the stock OS via the stock factory images is similar to the
|
|
process described above but with
|
|
<a href="https://flash.android.com/back-to-public">Google's web flashing
|
|
tool</a>. However, before flashing and locking, there's an additional step to
|
|
fully revert the device to a clean factory state.</p>
|
|
|
|
<p>The GrapheneOS factory images flash a non-stock Android Verified Boot key which
|
|
needs to be erased to fully revert back to a stock device state. Before flashing the
|
|
stock factory images and before locking the bootloader, you should erase the custom
|
|
Android Verified Boot key to untrust it:</p>
|
|
|
|
<button id="remove-custom-key-button" disabled="">Remove non-stock key</button>
|
|
|
|
<p><strong id="remove-custom-key-status"></strong></p>
|
|
</section>
|
|
|
|
<section id="further-information">
|
|
<h3><a href="#further-information">Further information</a></h3>
|
|
|
|
<p>Please look through the <a href="/usage">usage guide</a> and
|
|
<a href="/faq">FAQ</a> for more information. If you have further questions not
|
|
covered by the site, join the <a href="/contact#community">official GrapheneOS
|
|
chat channels</a> and ask the questions in the appropriate channel.</p>
|
|
</section>
|
|
</section>
|
|
</main>
|
|
<footer>
|
|
<a href="/"><img src="{{path|/mask-icon.svg}}" width="512" height="512" alt=""/>GrapheneOS</a>
|
|
<ul id="social">
|
|
<li><a href="https://twitter.com/GrapheneOS">Twitter</a></li>
|
|
<li><a href="https://github.com/GrapheneOS">GitHub</a></li>
|
|
<li><a href="https://reddit.com/r/GrapheneOS">Reddit</a></li>
|
|
<li><a href="https://www.linkedin.com/company/grapheneos/">LinkedIn</a></li>
|
|
</ul>
|
|
</footer>
|
|
</body>
|
|
</html>
|