DOCSEARCHbyAlgolia
Submit Docs

balenaEtcher

repository·master·Indexed 13 days ago

https://github.com/balena-io/etcher

A tool for safely flashing OS images to SD cards and USB drives. Version 2.1.6 features a modular architecture using Electron and NodeJS, designed to prevent accidental writes to hard drives and ensure data integrity.

Tokens
10K
Snippets
42
Records
72
Agent score
98%

What's inside Etcher

  2. How Etcher's modular architecture works

    master

    Etcher follows a "lego block approach" rather than being a monolithic project. The core functionality is split into decoupled modules, allowing logic to be reused by other applications and making the system more maintainable.

    Key architectural components include:

    • Drivelist: A specialized module responsible for detecting connected drives uniformly across all major operating systems. It provides metadata (such as whether a drive is removable) to prevent accidental writes to system drives.
    • Etcher (Main Repository): Acts as the front-end and the "glue" that integrates the various underlying modules and libraries into a cohesive application.

  3. Why some images (like Windows) are not bootable in Etcher

    master

    Etcher performs byte-by-byte copies without transformations. Consequently, images that require special handling to become bootable (such as Windows images) will not work out of the box.

    For these images, use specialized software:

    • Microsoft Windows: Use [Windows USB/DVD Download Tool], [Rufus], or [WoeUSB].
    • Windows 10 IoT: Use the [Windows 10 IoT Core Dashboard].

  6. Verify Unmounting behavior

    master

    Ensure Etcher handles drive unmounting correctly:

    • Manual Override: Verify behavior when unmounting is explicitly disabled during a flash.
    • Automatic Unmounting: When flashing an image with a file system that is readable by the host OS, ensure it is unmounted correctly after completion.

  9. Deactivate the AppImage desktop shortcut prompt on GNU/Linux

    master

    To prevent the AppImage from prompting you to register a desktop shortcut, you can either create a dummy file in one of the following locations:

    • $HOME/.local/share/appimagekit/no_desktopintegration
    • /usr/share/appimagekit/no_desktopintegration
    • /etc/appimagekit/no_desktopintegration

    Alternatively, set the SKIP environment variable to 1 when running the AppImage:

    SKIP=1 ./Etcher-linux-<arch>.AppImage

  10. Verify Flashing Process and Child Writer resilience

    master

    The flashing process must be resilient to interruptions. Ensure the following behaviors:

    Flashing Interruptions

    • Hardware Disconnection: Unplugging the drive during flash or validation.
    • Elevation Cancellation: Clicking "Flash", cancelling the elevation dialog, and then clicking "Flash" again.
    • Application Closure: Starting a flash, attempting to close Etcher, and cancelling the application close warning dialog should allow the flash to continue.

    Child Writer Lifecycle

    When the application is interrupted, the child writer process (the elevated process responsible for writing) must not remain alive. Test these scenarios:

    • Killing the child writer process via SIGINT or SIGKILL.
    • Closing the application via the window manager close icon.
    • Closing the application via OS keyboard shortcuts.
    • Closing the application from the terminal using Ctrl-C while flashing.
    • Force killing the application via a process monitor tool.

  12. Run Etcher on Wayland

    master

    Etcher runs on Wayland via the XWayland Server. On most mainstream GNU/Linux distributions, this works automatically. If Etcher fails to run, ensure the xwayland.so module is loaded in your weston.ini configuration file.

    [core]
modules=xwayland.so