diff options
| author | Daniel Micay <danielmicay@gmail.com> | 2021-01-24 10:47:09 -0500 |
|---|---|---|
| committer | Daniel Micay <danielmicay@gmail.com> | 2021-01-24 11:27:08 -0500 |
| commit | 4ff446e2d41515eaee5e89870e7b6fa85949033c (patch) | |
| tree | 5fa6b3d0c8b44533e27b80c9337315cdb2bd5696 /static/install | |
| parent | 5be9bc4f82ac3281267f9d9d500e0591e031e674 (diff) | |
create an install directory with an index page
Diffstat (limited to 'static/install')
| -rw-r--r-- | static/install/cli.html | 525 | ||||
| -rw-r--r-- | static/install/index.html | 71 | ||||
| -rw-r--r-- | static/install/web.html | 255 |
3 files changed, 851 insertions, 0 deletions
diff --git a/static/install/cli.html b/static/install/cli.html new file mode 100644 index 00000000..134ecc3c --- /dev/null +++ b/static/install/cli.html @@ -0,0 +1,525 @@ +<!DOCTYPE html> +<html lang="en" prefix="og: https://ogp.me/ns#"> + <head> + <meta charset="utf-8"/> + <title>Install | GrapheneOS</title> + <meta name="description" content="Command-line installation instructions for GrapheneOS, a security and privacy focused mobile OS with Android app compatibility."/> + <meta name="theme-color" content="#212121"/> + <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 install documentation"/> + <meta property="og:description" content="Command-line installation instructions 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/cli"/> + <link rel="canonical" href="https://grapheneos.org/install/cli"/> + <link rel="icon" sizes="16x16 24x24 32x32 48x48 64x64" type="image/vnd.microsoft.icon" href="/favicon.ico"/> + <link rel="icon" sizes="any" type="image/svg+xml" href="/mask-icon.svg"/> + <link rel="mask-icon" href="/mask-icon.svg" color="#1a1a1a"/> + <link rel="apple-touch-icon" href="/apple-touch-icon.png"/> + <link rel="stylesheet" href="/grapheneos.css?29"/> + <link rel="manifest" href="/manifest.webmanifest"/> + <link rel="license" href="/LICENSE.txt"/> + </head> + <body> + <header> + <nav id="site-menu"> + <ul> + <li><a href="/">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="/articles/">Articles</a></li> + <li><a href="/donate">Donate</a></li> + <li><a href="/contact">Contact</a></li> + </ul> + </nav> + </header> + <main id="install"> + <h1><a href="#install">Install</a></h1> + + <p>This is a guide on installing GrapheneOS for the + <a href="/faq#supported-devices">officially supported devices</a>. It can be followed + for both the <a href="/releases">official releases</a> and <a href="/build">custom + builds</a>.</p> + + <p>We strongly recommend following these official instructions. The official guide has + a lot of collaborative effort put into covering all of the edge cases and is regularly + tested by many people on each supported OS. Following these instructions to the letter + without skipping, reordering or adding any steps will give you a proper GrapheneOS + installation unless there's a hardware issue. We strongly recommend against following + unofficial guides deviating in any way from the official instructions.</p> + + <p>If you have trouble following this guide, 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. The official guide is the only supported + installation method. 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="#opening-terminal">Opening terminal</a></li> + <li> + <a href="#obtaining-fastboot">Obtaining fastboot</a> + <ul> + <li><a href="#standalone-platform-tools">Standalone platform-tools</a></li> + </ul> + </li> + <li><a href="#checking-fastboot-version">Checking fastboot version</a></li> + <li><a href="#fastboot-as-non-root">Fastboot as non-root</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-signify">Obtaining signify</a></li> + <li><a href="#obtaining-factory-images">Obtaining factory images</a></li> + <li> + <a href="#flashing-factory-images">Flashing factory images</a> + <ul> + <li><a href="#troubleshooting">Troubleshooting</a></li> + </ul> + </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 8GB 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>Windows 10, macOS Big Sur, Arch Linux, Debian buster and Ubuntu 20.04 LTS are the + officially supported operating systems for installing GrapheneOS. You should make sure + your operating system is up-to-date before proceeding with these instructions. Older + versions and other Linux distributions usually work, but if you encounter problems try + using one of the officially supported options.</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 stock OS on the device to make sure it's running + the latest firmware before proceeding with these instructions. This avoids running + into bugs, missing features or other differences in older firmware versions. You can + either update the device via over-the-air updates or sideload a full update, which for + Pixel phones can be obtained from the + <a href="https://developers.google.com/android/ota">full update package page</a>.</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 + pressing on the build number menu entry until developer mode is enabled.</p> + + <p>Next, go to Settings ➔ System ➔ Advanced ➔ Developer options and toggle on the + 'Enable 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="opening-terminal"> + <h2><a href="#opening-terminal">Opening terminal</a></h2> + + <p>These instructions use command-line tools. Launch the terminal as you would any + other application. On Windows, launch a regular non-administrator instance of the + PowerShell terminal. Do not use the legacy Command Prompt or administrator variant + of PowerShell.</p> + + <p>Use the same terminal for the whole installation process. If you close it, + you'll lose the setup of the environment for the installation.</p> + + <p>On Windows, run the following command to remove PowerShell's legacy curl alias + for the current shell to avoid needing to reference it as <code>curl.exe</code> + instead of <code>curl</code>:</p> + + <pre>Remove-Item Alias:Curl</pre> + </section> + + <section id="obtaining-fastboot"> + <h2><a href="#obtaining-fastboot">Obtaining fastboot</a></h2> + + <p>You need an updated copy of the <code>fastboot</code> tool and the + directory containing it needs to be included in the <code>PATH</code> + environment variable. You can run <code>fastboot --version</code> to determine + the current version. It must be at least <code>29.0.6</code>. You can use a + distribution package for this, but most of them mistakenly package development + snapshots of fastboot, clobber the standard version scheme for platform-tools + (adb, fastboot, etc.) with their own scheme and don't keep it up-to-date + despite that being crucial.</p> + + <p>On Arch Linux, install <code>android-tools</code> and skip the section below on + using the standalone release of platform-tools from Android:</p> + + <pre>sudo pacman -S android-tools</pre> + + <p>Debian and Ubuntu do not have a usable package for fastboot. Their packages for + these tools are both broken and many years out-of-date. Follow the instructions + below for platforms without a proper package.</p> + + <section id="standalone-platform-tools"> + <h3><a href="#standalone-platform-tools">Standalone platform-tools</a></h3> + + <!-- https://developer.android.com/studio/releases/platform-tools --> + + <p>If your operating system doesn't include a usable version of fastboot, + you can use the official standalone releases of platform-tools. This is + our recommendation for most users. The flashing process won't work unless + you follow these instructions including setting up PATH.</p> + + <p>To download, verify and extract the standalone platform-tools on Debian and + Ubuntu:</p> + + <pre>sudo apt install libarchive-tools +curl -O https://dl.google.com/android/repository/platform-tools_r30.0.5-linux.zip +echo 'd6d72d006c03bd55d49b6cef9f00295db02f0a31da10e121427e1f4cb43e7cb9 platform-tools_r30.0.5-linux.zip' | sha256sum -c +bsdtar xvf platform-tools_r30.0.5-linux.zip</pre> + + <p>To download, verify and extract the standalone platform-tools on macOS:</p> + + <pre>curl -O https://dl.google.com/android/repository/eabcd8b4b7ab518c6af9c941af8494072f17ec4b.platform-tools_r30.0.5-darwin.zip +echo 'SHA256 (eabcd8b4b7ab518c6af9c941af8494072f17ec4b.platform-tools_r30.0.5-darwin.zip) = e5780bad71a53cf9d693e1053a0748f49e4a67cc1f71d16a94ab4c943af3345f' | shasum -c +tar xvf eabcd8b4b7ab518c6af9c941af8494072f17ec4b.platform-tools_r30.0.5-darwin.zip</pre> + + <p>To download, verify and extract the standalone platform-tools on Windows:</p> + + <pre>curl -O https://dl.google.com/android/repository/platform-tools_r30.0.5-windows.zip +(Get-FileHash platform-tools_r30.0.5-windows.zip).hash -eq "549ba2bdc31f335eb8a504f005f77606a479cc216d6b64a3e8b64c780003661f" +tar xvf platform-tools_r30.0.5-windows.zip</pre> + + <p>Next, add the tools to your <code>PATH</code> in the current shell so they can be + used without referencing them by file path, enabling usage by the flashing script.</p> + + <p>On Debian, Ubuntu and macOS:</p> + + <pre>export PATH="$PWD/platform-tools:$PATH"</pre> + + <p>On Windows:</p> + + <pre>$env:Path = "$pwd\platform-tools;$env:Path"</pre> + + <p>This only changes <code>PATH</code> for the current shell and will need + to be done again if you open a new terminal.</p> + </section> + </section> + + <section id="checking-fastboot-version"> + <h2><a href="#checking-fastboot-version">Checking fastboot version</a></h2> + + <p>Check the output of <code>fastboot --version</code> before continuing.</p> + + <p>Example of the output after following the instructions above for the + standalone platform-tools:</p> + + <pre>fastboot version 30.0.5-6877874 +Installed as /home/username/platform-tools/fastboot</pre> + </section> + + <section id="fastboot-as-non-root"> + <h2><a href="#fastboot-as-non-root">Fastboot as non-root</a></h2> + + <p>On Linux, in order for the <code>fastboot</code> command to connect to a device + as non-root, the appropriate udev rules need to be set up. This is not an issue on + either macOS or Windows.</p> + + <p>On Arch Linux:</p> + + <pre>sudo pacman -S android-udev</pre> + + <p>On Debian and Ubuntu:</p> + + <pre>sudo apt install android-sdk-platform-tools-common</pre> + + <p>The udev rules on Debian and Ubuntu are very out-of-date but the package has + the rules needed for Pixel phones since the same USB IDs have been used for many + years.</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> + </section> + + <section id="unlocking-the-bootloader"> + <h2><a href="#unlocking-the-bootloader">Unlocking the bootloader</a></h2> + + <p>First, boot into the bootloader interface. You can do this by turning off the + device and then turning it on by holding both the Volume Down and Power buttons.</p> + + <p>Unlock the bootloader to allow flashing the OS and firmware:</p> + + <pre>fastboot flashing unlock</pre> + + <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> + </section> + + <section id="obtaining-signify"> + <h2><a href="#obtaining-signify">Obtaining signify</a></h2> + + <p>On the supported Linux distributions, the signify tool is used to verify the + download of the OS beyond the security offered by HTTPS. You should skip this on + macOS and Windows. It only makes sense to do this if you can obtain signify from + the distribution package repositories. GrapheneOS releases are hosted on our + servers and we do not have third party mirrors.</p> + + <p>On Arch Linux:</p> + + <pre>sudo pacman -S signify</pre> + + <p>On Debian and Ubuntu:</p> + + <pre>sudo apt install signify-openbsd +alias signify=signify-openbsd</pre> + + <p>On Debian-based distributions, the <code>signify</code> package and command are an + <a href="http://signify.sourceforge.net/" rel="nofollow">unmaintained mail-related + tool for generating mail signatures (not cryptographic signatures)</a> with the final + releases from 2003-2004 made directly by the developer via the Debian package without + upstream releases. Make sure to install <code>signify-openbsd</code>.</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>You can either download the files with your browser or using a command like + <code>curl</code>. It's generally easier to use the command-line since you're already + using it for the rest of the installation process, so these instructions use + <code>curl</code>.</p> + + <p>Download <a href="https://releases.grapheneos.org/factory.pub">the factory images + public key (factory.pub)</a> in order to verify the factory images:</p> + + <pre>curl -O https://releases.grapheneos.org/factory.pub</pre> + + <p>This is the content of <code>factory.pub</code>:</p> + + <pre>untrusted comment: GrapheneOS factory images public key +RWQZW9NItOuQYJ86EooQBxScfclrWiieJtAO9GpnfEjKbCO/3FriLGX3</pre> + + <p>The public key has also been published via the official + <a href="https://twitter.com/GrapheneOS/status/1145259815851253762">@GrapheneOS Twitter + account</a>, + <a href="https://www.reddit.com/r/GrapheneOS/comments/c7gb3f/grapheneos_factory_images_are_now_signed_with/esewpm9">the /u/GrapheneOS + Reddit account</a> and <a href="https://github.com/GrapheneOS/releases.grapheneos.org/blob/master/static/factory.pub">is available on GitHub</a>. + When the current signing key is replaced, the new key will be signed with it.</p> + + <p>Download the factory images for the device from <a href="/releases">the releases + page</a>. For example, to download the 2021.01.05.03 release for the Pixel 4a (sunfish):</p> + + <pre>curl -O https://releases.grapheneos.org/sunfish-factory-2021.01.05.03.zip +curl -O https://releases.grapheneos.org/sunfish-factory-2021.01.05.03.zip.sig</pre> + + <p>Verify the factory images using the signature if you were able to obtain + <code>signify</code> from trusted package repositories (see above), otherwise + continue on to the next section without this:</p> + + <pre>signify -Cqp factory.pub -x sunfish-factory-2021.01.05.03.zip.sig && echo verified</pre> + + <p>This will output <code>verified</code> if verification is successful. If something + goes wrong, it will output an error message rather than <code>verified</code>.</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> + + <p>Next, extract the factory images.</p> + + <p>On Linux:</p> + + <pre>bsdtar xvf sunfish-factory-2021.01.05.03.zip</pre> + + <p>On macOS and Windows:</p> + + <pre>tar xvf sunfish-factory-2021.01.05.03.zip</pre> + + <p>Move into the directory:</p> + + <pre>cd sunfish-factory-2021.01.05.03</pre> + + <p>Flash the images with the flash-all script in the directory.</p> + + <p>On Linux and macOS:</p> + + <pre>./flash-all.sh</pre> + + <p>On Windows:</p> + + <pre>./flash-all.bat</pre> + + <p>Wait for the flashing process to complete and proceed to + <a href="#locking-the-bootloader">locking the bootloader</a> before using the + device as locking wipes the data again.</p> + + <section id="troubleshooting"> + <h3><a href="#troubleshooting">Troubleshooting</a></h3> + + <p>The text output from a failed attempt at flashing will contain valuable + diagnostic information which is essential in knowing where and how the process + went wrong. Please provide this information when asking for help on the + GrapheneOS IRC / Matrix channel.</p> + + <p>A common issue on Linux distributions is that they mount the default temporary file + directory <code>/tmp</code> as tmpfs which results in it being backed by memory and + swap rather than persistent storage. By default, the size is 50% of the available + virtual memory. This is often not enough for the flashing process, especially since + <code>/tmp</code> is shared between applications and users. To use a different + temporary directory if your <code>/tmp</code> doesn't have enough space available:</p> + + <pre>mkdir tmp && TMPDIR="$PWD/tmp" ./flash-all.sh</pre> + </section> + </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> + + <pre>fastboot flashing lock</pre> + + <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> + </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 menu + 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> + </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. 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 + against 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 the same process + described above. However, before 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. After flashing the + stock factory images and before locking the bootloader, you should erase the custom + Android Verified Boot key to untrust it:</p> + + <pre>fastboot erase avb_custom_key</pre> + </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="/logo.png" 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> diff --git a/static/install/index.html b/static/install/index.html new file mode 100644 index 00000000..430eeae8 --- /dev/null +++ b/static/install/index.html @@ -0,0 +1,71 @@ +<!DOCTYPE html> +<html lang="en" prefix="og: https://ogp.me/ns#"> + <head> + <meta charset="utf-8"/> + <title>Install | GrapheneOS</title> + <meta name="description" content="Installation instructions for GrapheneOS, a security and privacy focused mobile OS with Android app compatibility."/> + <meta name="theme-color" content="#212121"/> + <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 install documentation"/> + <meta property="og:description" content="Installation instructions 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/"/> + <link rel="canonical" href="https://grapheneos.org/install/"/> + <link rel="icon" sizes="16x16 24x24 32x32 48x48 64x64" type="image/vnd.microsoft.icon" href="/favicon.ico"/> + <link rel="icon" sizes="any" type="image/svg+xml" href="/mask-icon.svg"/> + <link rel="mask-icon" href="/mask-icon.svg" color="#1a1a1a"/> + <link rel="apple-touch-icon" href="/apple-touch-icon.png"/> + <link rel="stylesheet" href="/grapheneos.css?29"/> + <link rel="manifest" href="/manifest.webmanifest"/> + <link rel="license" href="/LICENSE.txt"/> + </head> + <body> + <header> + <nav id="site-menu"> + <ul> + <li><a href="/">GrapheneOS</a></li> + <li><a href="/features">Features</a></li> + <li aria-current="page"><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="/articles/">Articles</a></li> + <li><a href="/donate">Donate</a></li> + <li><a href="/contact">Contact</a></li> + </ul> + </nav> + </header> + <main id="install"> + <h1><a href="#install">Install</a></h1> + + <p>GrapheneOS has two officially supported installation methods. You can either use + the <a href="/install/cli">command-line installation guide</a> or the experimental + <a href="/install/web">WebUSB-based installer</a>.</p> + + <p>The command-line approach offers a way to install GrapheneOS without trusting our + server infrastructure. This requires being on an OS with proper fastboot and signify + packages along with understanding the process enough to avoid blindly trusting the + instructions from our site. For most users, the web-based installation approach is no + less secure and avoids needing any software beyond a browser with WebUSB support.</p> + </main> + <footer> + <a href="/"><img src="/logo.png" 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> diff --git a/static/install/web.html b/static/install/web.html new file mode 100644 index 00000000..114ae719 --- /dev/null +++ b/static/install/web.html @@ -0,0 +1,255 @@ +<!DOCTYPE html> +<html lang="en" prefix="og: https://ogp.me/ns#"> + <head> + <meta charset="utf-8"/> + <title>Web 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="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 install"/> + <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" sizes="16x16 24x24 32x32 48x48 64x64" type="image/vnd.microsoft.icon" href="/favicon.ico"/> + <link rel="icon" sizes="any" type="image/svg+xml" href="/mask-icon.svg"/> + <link rel="mask-icon" href="/mask-icon.svg" color="#1a1a1a"/> + <link rel="apple-touch-icon" href="/apple-touch-icon.png"/> + <link rel="stylesheet" href="/grapheneos.css?29"/> + <link rel="manifest" href="/manifest.webmanifest"/> + <link rel="license" href="/LICENSE.txt"/> + <script type="module" src="/js/fastboot/dist/fastboot.min.js?0"></script> + <script type="module" src="/js/web-install.js?4"></script> + </head> + <body> + <header> + <nav id="site-menu"> + <ul> + <li><a href="/">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="/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 install</a></h1> + + <p><strong>This is an experimental WebUSB-based installer for GrapheneOS. Consider + using the <a href="/install/cli">command-line installation guide</a> until this has + been more thoroughly tested and improved.</strong></p> + + <section id="prerequisites"> + <h2><a href="#prerequisites">Prerequisites</a></h2> + + <p>You should have at least 2GB of free memory available and 8GB 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>Windows 10, macOS Big Sur, Arch Linux, Debian buster and Ubuntu 20.04 LTS are the + officially supported operating systems for installing GrapheneOS. You should make sure + your operating system is up-to-date before proceeding with these instructions. Older + versions and other Linux distributions usually work, but if you encounter problems try + using one of the officially supported options.</p> + + <p>For this web-based installation process, the latest stable release of Chromium + or Chrome is recommended.</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 stock OS on the device to make sure it's running + the latest firmware before proceeding with these instructions. This avoids running + into bugs, missing features or other differences in older firmware versions. You can + either update the device via over-the-air updates or sideload a full update, which for + Pixel phones can be obtained from the + <a href="https://developers.google.com/android/ota">full update package page</a>.</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 + pressing on the build number menu entry until developer mode is enabled.</p> + + <p>Next, go to Settings ➔ System ➔ Advanced ➔ Developer options and toggle on the + 'Enable 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="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> + </section> + + <section id="unlocking-the-bootloader"> + <h2><a href="#unlocking-the-bootloader">Unlocking the bootloader</a></h2> + + <p>First, boot into the bootloader interface. You can do this by turning off the + device and then turning it on by holding both the Volume Down and Power buttons.</p> + + <p>Unlock the bootloader to allow flashing the OS and firmware:</p> + + <button id="unlock-bootloader-button" disabled="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="disabled">Download release</button> + + <p><strong id="download-release-status"></strong></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="disabled">Flash release</button> + + <p>Wait for the flashing process to complete and proceed to + <a href="#locking-the-bootloader">locking the bootloader</a> before using the + device as locking wipes the data again.</p> + + <p><strong id="flash-release-status"></strong></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="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 menu + 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> + </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. 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 + against 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="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="/logo.png" 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> |