Differences
This shows you the differences between two versions of the page.
| Both sides previous revision Previous revision Next revision | Previous revision Next revisionBoth sides next revision | ||
| docs:guide-user:additional-software:imagebuilder [2021/07/28 12:09] – update, optimize formatting vgaetera | docs:guide-user:additional-software:imagebuilder [2024/04/01 16:18] – [Arch / Manjaro / EndeavourOS] sixx | ||
|---|---|---|---|
| Line 1: | Line 1: | ||
| ====== Using the Image Builder ====== | ====== Using the Image Builder ====== | ||
| + | See also: | ||
| + | [[docs: | ||
| + | [[docs: | ||
| + | [[docs: | ||
| + | |||
| The Image Builder (previously called the Image Generator) is a pre-compiled environment suitable for creating custom images without the need for compiling them from source. | The Image Builder (previously called the Image Generator) is a pre-compiled environment suitable for creating custom images without the need for compiling them from source. | ||
| It downloads pre-compiled packages and integrates them in a single flashable image. | It downloads pre-compiled packages and integrates them in a single flashable image. | ||
| Line 8: | Line 13: | ||
| * your device has 32MB or less RAM and opkg does not work properly | * your device has 32MB or less RAM and opkg does not work properly | ||
| * you want to mass-flash dozens of devices and you need a specific firmware setup | * you want to mass-flash dozens of devices and you need a specific firmware setup | ||
| - | |||
| - | Alternative guides to achieving the same goal: | ||
| - | [[docs: | ||
| - | [[docs: | ||
| - | |||
| - | Consider also removing packages if you have a device with very little firmware space: | ||
| - | [[docs: | ||
| <WRAP important> | <WRAP important> | ||
| - | Imagebuilder | + | The Image Builder |
| When recent/ | When recent/ | ||
| </ | </ | ||
| - | |||
| - | ===== Frontends based on imagebuilder ===== | ||
| - | There are several tools that provide a frontend interface to the imagebuilder (either web-interface, | ||
| - | |||
| - | See [[docs: | ||
| ===== Prerequisites ===== | ===== Prerequisites ===== | ||
| <WRAP important> | <WRAP important> | ||
| * The Image Builder runs only in 64-bit Linux. You can however run a 64-bit Linux in PC or VM, e.g. VirtualBox, even from 32-bit Windows. | * The Image Builder runs only in 64-bit Linux. You can however run a 64-bit Linux in PC or VM, e.g. VirtualBox, even from 32-bit Windows. | ||
| - | * The Image Builder has similar prerequisites as [[docs: | + | * The Image Builder has similar prerequisites as the [[docs: |
| </ | </ | ||
| Example dependencies in the most common distros: | Example dependencies in the most common distros: | ||
| - | ==== Arch / Manjaro | + | ==== Arch ==== |
| <code bash> | <code bash> | ||
| sudo pacman -S --needed base-devel ncurses zlib gawk git gettext \ | sudo pacman -S --needed base-devel ncurses zlib gawk git gettext \ | ||
| Line 40: | Line 33: | ||
| </ | </ | ||
| - | ==== CentOS / Fedora ==== | + | ==== Fedora ==== |
| <code bash> | <code bash> | ||
| sudo dnf install git gawk gettext ncurses-devel zlib-devel \ | sudo dnf install git gawk gettext ncurses-devel zlib-devel \ | ||
| openssl-devel libxslt wget which @c-development @development-tools \ | openssl-devel libxslt wget which @c-development @development-tools \ | ||
| - | @development-libs zlib-static which python3 | + | @development-libs zlib-static which python3 |
| </ | </ | ||
| - | ==== Debian / Ubuntu ==== | + | ==== Debian |
| <code bash> | <code bash> | ||
| - | sudo apt install build-essential | + | sudo apt install build-essential |
| - | zlib1g-dev gawk git gettext libssl-dev xsltproc rsync wget unzip python | + | gettext libssl-dev xsltproc rsync wget unzip python3 python3-distutils |
| </ | </ | ||
| + | ==== WSL ==== | ||
| + | This method is NOT OFFICIALLY supported. | ||
| + | But it works. | ||
| + | |||
| + | [[docs: | ||
| ===== Obtaining the Image Builder ===== | ===== Obtaining the Image Builder ===== | ||
| You can download an archive that contains the **Image Builder**, it is usually located in the same download page where you find the firmware image for your device. | You can download an archive that contains the **Image Builder**, it is usually located in the same download page where you find the firmware image for your device. | ||
| Line 66: | Line 64: | ||
| All operations should be performed with a non-root user account. | All operations should be performed with a non-root user account. | ||
| </ | </ | ||
| + | |||
| + | Unpack the archive and change the working directory: | ||
| <code bash> | <code bash> | ||
| - | # Unpack | + | tar -J -x -f openwrt-imagebuilder-*.tar.xz |
| - | tar xJf openwrt*.tar.xz | + | cd openwrt-imagebuilder-*/ |
| + | </ | ||
| - | # Change directory | + | The image building can be customized with the following variables: |
| - | cd openwrt* | + | |
| - | # Build images | + | ^ Variable ^ Description ^ |
| - | make ... | + | | '' |
| + | | '' | ||
| + | | '' | ||
| + | | '' | ||
| + | | '' | ||
| + | | '' | ||
| + | |||
| + | Run '' | ||
| + | |||
| + | ==== Selecting profile ==== | ||
| + | The '' | ||
| + | |||
| + | <code bash> | ||
| + | PROFILE=" | ||
| </ | </ | ||
| - | ==== make help ==== | + | Run '' |
| + | |||
| + | ==== Selecting packages ==== | ||
| + | The '' | ||
| + | By default (empty PACKAGES variable) the Image Builder will create a minimal image with device-specific kernel and drivers, uci, ssh, switch, firewall, ppp and ipv6 support. | ||
| + | |||
| + | <code bash> | ||
| + | PACKAGES=" | ||
| + | </ | ||
| + | |||
| + | The example above will include pkg1, pkg2, pkg3, and exclude pkg4, pkg5, pkg6, note the " | ||
| + | |||
| + | You don't need to list all dependencies of the packages you need in this list, the Image Builder uses '' | ||
| + | |||
| + | The list of currently installed packages on your device can be obtained with the following command: | ||
| + | |||
| + | <code bash> | ||
| + | echo $(opkg list-installed | sed -e " | ||
| + | </ | ||
| + | |||
| + | <WRAP important> | ||
| + | Many devices are limited in storage capacity and there is no guarantee that the build system will detect when you have added too many packages to fit into the device storage space, which may render the device unbootable if installed. | ||
| + | If in doubt, do not go overboard. | ||
| + | Use what you had installed on the device last as a guide or create a minimal image first, install it to the device and test what you would like to add first. | ||
| + | Consider removing unnecessary packages to [[docs: | ||
| + | </ | ||
| + | |||
| + | In addition ABI versioned packages such as '' | ||
| + | You may get compile errors when these are provided as packages. | ||
| + | To avoid issues you should omit them from image builder and let the correct versions be installed via package dependencies. | ||
| + | The '' | ||
| + | |||
| + | ==== Custom packages ==== | ||
| + | If there is a custom package or ipk you would prefer to use create a '' | ||
| + | |||
| + | ==== Custom files ==== | ||
| + | The '' | ||
| + | This is especially useful if you need to change the network configuration from default before flashing, or if you are preparing an image for mass-flashing many devices. | ||
| + | |||
| + | <code bash> | ||
| + | FILES=" | ||
| + | </ | ||
| + | |||
| + | The '' | ||
| + | |||
| + | It is strongly recommended to use [[docs: | ||
| + | This helps minimize conflicts with auto-generated settings which can change between versions. | ||
| + | |||
| + | see: [[: | ||
| + | |||
| + | ==== Building image ==== | ||
| + | After you select the appropriate profile, packages and custom files, pass it to the '' | ||
| + | |||
| + | <code bash> | ||
| + | make image \ | ||
| + | PROFILE=" | ||
| + | PACKAGES=" | ||
| + | FILES=" | ||
| + | DISABLED_SERVICES=" | ||
| + | </ | ||
| + | |||
| + | After the make command is finished, the generated images are stored in the bin/// | ||
| + | |||
| + | The built image will be found under the subdirectory '' | ||
| + | |||
| + | ==== Cleaning up ==== | ||
| + | To clean up temporary build files and generated images, use the '' | ||
| + | |||
| + | ==== Examples ==== | ||
| + | The following example shows: | ||
| + | * Creating the directory for the configuration files. | ||
| + | * Using '' | ||
| + | * Generating an image for WL500GP with custom packages and '' | ||
| + | |||
| + | <code bash> | ||
| + | mkdir -p files/ | ||
| + | scp root@192.168.1.1:/ | ||
| + | scp root@192.168.1.1:/ | ||
| + | scp root@192.168.1.1:/ | ||
| + | make image \ | ||
| + | PROFILE=" | ||
| + | PACKAGES=" | ||
| + | FILES=" | ||
| + | DISABLED_SERVICES=" | ||
| + | </ | ||
| + | |||
| + | ===== Troubleshooting ===== | ||
| + | - Did you run everything as a non-root user? | ||
| + | - Check the logged output, are there package issues (conflicts, improper names)? | ||
| + | - Check the logged output, did you exceed maximum space? | ||
| + | - Check the logged output, are there other obvious errors? | ||
| + | - Wait a few hours/ | ||
| + | - Verify you have a supported OS, prerequisites, | ||
| + | |||
| + | ===== Extras ===== | ||
| + | The topics below go beyond simple usage and aimed at developers and advanced users. | ||
| + | |||
| + | ==== Detailed | ||
| + | See also: [[https:// | ||
| + | |||
| + | Getting detailed help: | ||
| < | < | ||
| # make help | # make help | ||
| Line 110: | Line 224: | ||
| </ | </ | ||
| - | ==== make image ==== | + | ==== Available profiles |
| - | **make image** without specifying the '' | + | Listing available |
| - | + | ||
| - | To change this not-so-useful default behavior you can use some variables passed as arguments: | + | |
| - | + | ||
| - | * //'' | + | |
| - | * //'' | + | |
| - | * //'' | + | |
| - | * //'' | + | |
| - | * //'' | + | |
| - | * //'' | + | |
| - | + | ||
| - | (see also the makefile used, [[https:// | + | |
| - | + | ||
| - | Example syntax: | + | |
| - | + | ||
| - | <code bash> | + | |
| - | make image PROFILE=XXX PACKAGES=" | + | |
| - | </ | + | |
| - | + | ||
| - | See the sections below for a more in-depth explanation. | + | |
| - | After the make command is finished, the generated images are stored in the bin/// | + | |
| - | + | ||
| - | The built image will be found under the subdirectory '' | + | |
| - | + | ||
| - | ==== PROFILE Variable ===== | + | |
| - | Syntax: | + | |
| - | + | ||
| - | <code bash> | + | |
| - | make image PROFILE=NAME_OF_PROFILE | + | |
| - | </ | + | |
| - | + | ||
| - | === Pre-defined Profiles === | + | |
| - | Run '' | + | |
| - | + | ||
| - | Example output is listed below: | + | |
| < | < | ||
| Line 173: | Line 253: | ||
| </ | </ | ||
| - | After you find the appropriate profile pass it to the '' | + | ==== Building the Image Builder |
| - | + | It is possible to use a buildroot to create your own Image Builder | |
| - | For example, if we wanted to generate a default image for for Asus RT-N14u (from above). | + | |
| - | + | ||
| - | <code bash> | + | |
| - | make image PROFILE=rt-n14u | + | |
| - | </ | + | |
| - | + | ||
| - | ==== PACKAGES Variable ==== | + | |
| - | The '' | + | |
| - | By default (empty PACKAGES variable) the Image Generator will create a minimal image with device-specific kernel and drivers, uci, ssh, switch, firewall, ppp and ipv6 support. | + | |
| - | + | ||
| - | Syntax: | + | |
| - | + | ||
| - | <code bash> | + | |
| - | make image PACKAGES=" | + | |
| - | </ | + | |
| - | + | ||
| - | The example above will include pkg1, pkg2, pkg3, and exclude pkg4, pkg5, pkg6, note the " | + | |
| - | + | ||
| - | You don't need to list all dependencies of the packages you need in this list, the Image Generator uses '' | + | |
| - | + | ||
| - | **Tip:** The list of currently installed packages on your device can be obtained with the command below: | + | |
| - | + | ||
| - | <code bash> | + | |
| - | echo $(opkg list_installed | sed -e " | + | |
| - | </ | + | |
| - | + | ||
| - | <WRAP center round important 60%> | + | |
| - | Many devices are limited in storage capacity and there is no guarantee that the build system will detect when you have added too many packages to fit into the device storage space, which may render the device unbootable if installed. | + | |
| - | If in doubt, do not go overboard. | + | |
| - | Use what you had installed on the device last as a guide or create a minimal image first, install it to the device and test what you would like to add first. | + | |
| - | </ | + | |
| - | + | ||
| - | === Custom packages === | + | |
| - | If there is a custom package or ipk you would prefer to use create a " | + | |
| - | + | ||
| - | ==== Custom files ==== | + | |
| - | The '' | + | |
| - | This is especially useful if you need to change the network configuration from default before flashing, or if you are preparing an image for mass-flashing many devices. | + | |
| - | + | ||
| - | Syntax: | + | |
| - | + | ||
| - | <code bash> | + | |
| - | make image FILES=files/ | + | |
| - | </ | + | |
| - | + | ||
| - | **Note:** The '' | + | |
| - | + | ||
| - | ==== Examples ==== | + | |
| - | The following example shows: | + | |
| - | -Creating the directory for the configuration files | + | |
| - | -Using '' | + | |
| - | -Generating an image for WL500GP with custom packages and '' | + | |
| - | + | ||
| - | <code bash> | + | |
| - | mkdir -p files/ | + | |
| - | scp root@192.168.1.1:/ | + | |
| - | scp root@192.168.1.1:/ | + | |
| - | scp root@192.168.1.1:/ | + | |
| - | make image PROFILE=wl500gp PACKAGES=" | + | |
| - | </ | + | |
| - | + | ||
| - | ===== Cleanup ===== | + | |
| - | To clean up temporary build files and generated images, use the **make clean** command. | + | |
| - | + | ||
| - | ===== Building the Image Generator | + | |
| - | It is possible to use a **buildroot*** to create your own Image Generator | + | |
| In the graphical configuration, | In the graphical configuration, | ||
| - | Then build the image, including '' | + | You can [[docs: |
| - | Enabling | + | Don't call '' |
| - | <code bash> | + | ==== Adding package repositories ==== |
| - | make IGNORE_ERRORS=1 | + | The Image Builder |
| - | </ | + | |
| - | + | ||
| - | **Note:** Don't call '' | + | |
| - | + | ||
| - | ====== Extras ====== | + | |
| - | The topics below go beyond simple usage and aimed at developers and advanced users. | + | |
| - | + | ||
| - | ===== Adding package repositories | + | |
| - | The **Image Generator** | + | |
| The package sources are configured in the '' | The package sources are configured in the '' | ||
| Sources are specified in //opkg// native config format. | Sources are specified in //opkg// native config format. | ||
| Line 283: | Line 288: | ||
| The '' | The '' | ||
| - | If you want to add a custom local repository, copy the '' | + | If you want to add a custom local repository, copy the '' |
| If you have problems with using you local repository because the " | If you have problems with using you local repository because the " | ||
| Line 290: | Line 295: | ||
| NOTE: if you want to override packages coming from an existing feed, you must write your custom feed ABOVE the line of the package feed containing the packages you want to override, as shown in the examples above. | NOTE: if you want to override packages coming from an existing feed, you must write your custom feed ABOVE the line of the package feed containing the packages you want to override, as shown in the examples above. | ||
| - | ===== Adding/ | + | ==== Restricting root access ==== |
| - | The image generation | + | Create a non-privileged admin user and lock root password. |
| + | Configure privilege elevation with sudo. | ||
| + | Set up key-based authentication and disable password authentication for Dropbear. | ||
| + | |||
| + | <code bash> | ||
| + | mkdir -p files/ | ||
| + | cat << " | ||
| + | USER_NAME=" | ||
| + | USER_SSHPUB=" | ||
| + | USER_SHELL="/ | ||
| + | SUDO_USER=" | ||
| + | SUDO_GROUP=" | ||
| + | groupadd -r " | ||
| + | useradd -m -G " | ||
| + | passwd -l " | ||
| + | cat << EOI > / | ||
| + | %${SUDO_GROUP} ALL=(ALL) ALL | ||
| + | EOI | ||
| + | USER_HOME=" | ||
| + | mkdir -p " | ||
| + | cat << EOI > " | ||
| + | ${USER_SSHPUB} | ||
| + | EOI | ||
| + | uci set dropbear.@dropbear[0].PasswordAuth=" | ||
| + | uci set dropbear.@dropbear[0].RootPasswordAuth=" | ||
| + | uci commit dropbear | ||
| + | / | ||
| + | EOF | ||
| + | make image \ | ||
| + | FILES=" | ||
| + | PACKAGES=" | ||
| + | </ | ||
| + | |||
| + | ==== Adding/ | ||
| + | |||
| + | <WRAP important> | ||
| + | Examples below may contain version dependent / legacy information and are for informational purposes. They are very low level so expect to have a good level of skill and familiarity with the ImageBuilder / OpenWrt in general. | ||
| + | </ | ||
| + | |||
| + | The image building | ||
| If you add a new profile without also adding an appropriate macro to the image-generation Makefile, no suitable firmware file will get generated when using the custom profile. | If you add a new profile without also adding an appropriate macro to the image-generation Makefile, no suitable firmware file will get generated when using the custom profile. | ||
| - | :!: Make sure to remove | + | Remove |
| The location of the profiles for the pre-compiled package for // | The location of the profiles for the pre-compiled package for // | ||
| Line 317: | Line 361: | ||
| An "ls -a" will reveal the files hidden in the various directories. | An "ls -a" will reveal the files hidden in the various directories. | ||
| - | ===== Removing useless files from firmware | + | ==== Removing useless files from firmware ==== |
| <WRAP important> | <WRAP important> | ||
| This is not a standard feature of the Image Builder. | This is not a standard feature of the Image Builder. | ||
| Line 324: | Line 368: | ||
| Note that it requires patching of the '' | Note that it requires patching of the '' | ||
| + | |||
| + | It is based on older Chaos Calmer era code... and not applicable to modern ImageBuilders but useful as a reference... | ||
| </ | </ | ||
| Line 359: | Line 405: | ||
| <code bash> | <code bash> | ||
| make image \ | make image \ | ||
| - | | + | PROFILE="tlwr841" |
| - | PACKAGES=" | + | PACKAGES=" |
| - | FILES_REMOVE=" | + | FILES_REMOVE=" |
| </ | </ | ||
| - | |||