Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
Next revisionBoth sides next revision
docs:guide-user:additional-software:imagebuilder [2021/07/28 06:49] – [Usage] formatting someothertimedocs:guide-user:additional-software:imagebuilder [2024/04/01 16:19] – [Debian 12+ / Ubuntu / Mint] sixx
Line 1: Line 1:
 ====== Using the Image Builder ====== ====== Using the Image Builder ======
 +See also:
 +[[docs:guide-developer:imagebuilder_frontends|Image Builder frontends]],
 +[[docs:guide-developer:start#using_the_toolchain|Using the toolchain]],
 +[[docs:guide-developer:toolchain:beginners-build-guide|Quick image building guide]]
  
-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.
  
-Doing so is useful if: +Doing so is useful if:
   * you want to fit more packages in a small flash size   * you want to fit more packages in a small flash size
   * you want to follow development snapshots   * you want to follow development snapshots
Line 10: Line 14:
   * 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: +<WRAP important> 
-[[docs:guide-developer:quickstart-build-images|Quick Image Building Guide]], +The Image Builder images are not identical to official images as they obtain pre-generated packages. 
-[[docs:guide-user:additional-software:beginners-build-guide|Beginners guide to building your own firmware]]. +When recent/important changes are made, there can be some delay for these packages to propagate and it is best to check that packages were uploaded after the date of the imagebuilder/change.
- +
-Consider also removing packages if you have a device with very little firmware space: +
-[[docs:guide-user:additional-software:saving_space|Saving Firmware Space]]. +
- +
-<WRAP center round important 60%+
-Imagebuilder images are not identical to official images as they obtain pre-generated packages. When recent/important changes are made, there can be some delay for these packages to propagate and it is best to check that packages were uploaded after the date of the imagebuilder/change.+
 </WRAP> </WRAP>
-===== Frontends based on imagebuilder ===== 
- 
-There are several tools that provide a frontend interface to the imagebuilder (either web-interface, or template-based) 
- 
-See [[docs:guide-developer:imagebuilder_frontends|ImageBuilder frontends]]. 
  
 ===== Prerequisites ===== ===== Prerequisites =====
-:!: The Image Builder runs only in 64bit linux. You can however run a 64bit linux in VM (i.e. virtualbox) even from 32bit windows.\\ +<WRAP important> 
-:!: The Image Builder has similar prerequisites as [[docs:guide-developer:build-system:install-buildsystem|Build system setup]].+  * The Image Builder runs only in 64-bit Linux. You can however run a 64-bit Linux in PC or VMe.g. VirtualBox, even from 32-bit Windows
 +  The Image Builder has similar prerequisites as the [[docs:guide-developer:toolchain:install-buildsystem|Build system]]. 
 +</WRAP>
  
 Example dependencies in the most common distros: Example dependencies in the most common distros:
  
-==== Arch / Manjaro ====+==== Arch ====
 <code bash> <code bash>
-pacman -S --needed base-devel ncurses zlib gawk git gettext \+sudo pacman -S --needed base-devel ncurses zlib gawk git gettext \
 openssl libxslt wget unzip python openssl libxslt wget unzip python
 </code> </code>
  
-==== CentOS / Fedora ====+==== Fedora ====
 <code bash> <code bash>
-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 perl
 </code> </code>
  
-==== Debian / Ubuntu ====+==== Debian / Ubuntu / Mint ====
 <code bash> <code bash>
-apt install build-essential libncurses5-dev libncursesw5-dev \ +sudo apt install build-essential libncurses-dev zlib1g-dev gawk git 
-zlib1g-dev gawk git gettext libssl-dev xsltproc rsync wget unzip python+gettext libssl-dev xsltproc rsync wget unzip python3 python3-distutils
 </code> </code>
  
 +==== WSL ====
 +This method is NOT OFFICIALLY supported.
 +But it works.
 +
 +[[docs:guide-developer:toolchain:wsl|Build system setup WSL]]
 ===== 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. 
-For example, this is the page where you can download all firmware images for **ath79/generic** devices\\  + 
-https://downloads.openwrt.org/snapshots/targets/ath79/generic/ .\\+For example, this is the page where you can download all firmware images for **ath79/generic** devices: 
 +[[https://downloads.openwrt.org/snapshots/targets/ath79/generic/]]
 and you will find a **openwrt-imagebuilder-ath79-generic.Linux-x86_64.tar.xz** archive with the image builder in it. and you will find a **openwrt-imagebuilder-ath79-generic.Linux-x86_64.tar.xz** archive with the image builder in it.
-Also, it is always created by the build system because it is needed to create the image file. If the option "**Build the OpenWrt Image Builder**" is enabled, the image builder will be generated in the same folder you find firmware images (''source/bin/targets/xxx'') and you can use it to create more images from the packages you obtained during compilation.+Also, it is always created by the build system because it is needed to create the image file. 
 +If the option "**Build the OpenWrt Image Builder**" is enabled, the image builder will be generated in the same folder you find firmware images (''source/bin/targets/xxx'') and you can use it to create more images from the packages you obtained during compilation.
  
-----+===== Usage ===== 
 +<WRAP important> 
 +All operations should be performed with a non-root user account. 
 +</WRAP>
  
-===== Add Package Repositories (optional) ===== +Unpack the archive and change the working directory:
-The **Image Generator** you download from the OpenWrt pages is already configured to download any non-default packages from official repositories.\\  +
-The package sources are configured in the ''repositories.conf'' file in the extracted directory. Sources are specified in //opkg// native config format. This can be either the official package repositories or custom generated repositories.+
  
-An example of the contents of the ''repositories.conf'' from the **openwrt-imagebuilder-18.06.0-rc2-ramips-mt7621.Linux-x86_64.tar.xz** :+<code bash> 
 +tar ---f openwrt-imagebuilder-*.tar.xz 
 +cd openwrt-imagebuilder-*
 +</code>
  
-<code>## Place your custom repositories here, they must match the architecture and version. +The image building can be customized with the following variables:
-# src/gz %n http://downloads.openwrt.org/releases/18.06.0-rc2 +
-# src custom file:///usr/src/openwrt/bin/ramips/packages+
  
-## Remote package repositories +^ Variable ^ Description ^ 
-src/gz openwrt_core http://downloads.openwrt.org/releases/18.06.0-rc2/targets/ramips/mt7621/packages +| ''PROFILE'' | Specifies the target image to build | 
-src/gz openwrt_base http://downloads.openwrt.org/releases/18.06.0-rc2/packages/mipsel_24kc/base +| ''PACKAGES'' | A list of packages to embed into the image | 
-src/gz openwrt_luci http://downloads.openwrt.org/releases/18.06.0-rc2/packages/mipsel_24kc/luci +| ''FILES'' | Directory with custom files to include | 
-src/gz openwrt_packages http://downloads.openwrt.org/releases/18.06.0-rc2/packages/mipsel_24kc/packages +| ''BIN_DIR'' | Alternative output directory for the images | 
-src/gz openwrt_routing http://downloads.openwrt.org/releases/18.06.0-rc2/packages/mipsel_24kc/routing +| ''EXTRA_IMAGE_NAME'' | Add this to the output image filename (sanitized) | 
-src/gz openwrt_telephony http://downloads.openwrt.org/releases/18.06.0-rc2/packages/mipsel_24kc/telephony+| ''DISABLED_SERVICES'' | A list of services to disable | 
 + 
 +Run ''make help'' to get [[docs:guide-user:additional-software:imagebuilder#detailed_help|detailed help]].
  
-## This is the local package repository, do not remove! +==== Selecting profile ==== 
-src imagebuilder file:packages+The ''PROFILE'' variable specifies the target image to build. 
 + 
 +<code bash> 
 +PROFILE="profile-name"
 </code> </code>
  
-The ''repositories.conf'' in an imagebuilder you compile from source will lack the "Remote package repositories" links.+Run ''make info'' to obtain a list of [[docs:guide-user:additional-software:imagebuilder#available_profiles|available profiles]].
  
-If you want to add a custom local repository, copy the <code>src custom file:///usr/src/openwrt/bin/ramips/packages</code> line and modify it to point to the local folder you have your packages and package lists inIf you have problems with using you local repository because the "Signature check failed" then remove the line ''option check_signature'' from ''repositories.conf''\\+==== Selecting packages ==== 
 +The ''PACKAGES'' variable allows to include and/or exclude packages in the firmware image. 
 +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.
  
-If you have custom repositories online, copy and modify the <code>src/gz reboot http://downloads.openwrt.org/snapshots</code> line instead.+<code bash> 
 +PACKAGES="pkg1 pkg2 pkg3 -pkg4 -pkg5 -pkg6" 
 +</code>
  
 +The example above will include pkg1, pkg2, pkg3, and exclude pkg4, pkg5, pkg6, note the "-" before each excluded package.
  
-NOTE: if you want to override packages coming from an existing feedyou 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.\\ +You don't need to list all dependencies of the packages you need in this list, the Image Builder uses ''opkg'' to resolve automatically the package dependencies and install other required packages.
-===== Usage =====+
  
-All operations should be performed using a general ( non-root ) user account.+The list of currently installed packages on your device can be obtained with the following command:
  
-**Unpacking:** +<code bash
-<code> +echo $(opkg list-installed | sed -e "s/\s.*$//")
-tar xJf openwrt*.tar.xz #changedir: cd openwrt... +
 </code> </code>
  
 +<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:guide-user:additional-software:saving_space|save firmware space]].
 +</WRAP>
  
-==== make image ==== +In addition ABI versioned packages such as ''libubus20191227'' or similar may cause problems with image builder. 
-**make image** without specifying the ''PROFILE'' for your device is almost certainly not what you want.+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 ''%%--strip-abi%%'' parameter can be used to export a normalized package list.
  
-To change this not-so-useful default behavior you can use some variables passed as arguments:+==== Custom packages ==== 
 +If there is a custom package or ipk you would prefer to use create a ''packages'' directory if one does not exist and place your custom ipk within this directory.
  
-  * //''PROFILE''// - specifies the target image to build +==== Custom files ==== 
-  * //''PACKAGES''// - a list of packages to embed into the image +The ''FILES'' variable allows custom configuration files to be included in images built with Image Builder. 
-  * //''FILES''// - directory with custom files to include +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.
-  * //''BIN_DIR''// - alternative output directory for the images +
-  * //''EXTRA_IMAGE_NAME''// - Add this to the output image filename (sanitized) +
-  * //''DISABLED_SERVICES''// Which services in /etc/init.d/ should be disabled. Use the initscript name you find in  /etc/init.d, so for example "**dhcp**" for dnsmasq.+
  
-(see also the makefile used, [[https://github.com/openwrt/openwrt/blob/master/target/imagebuilder/files/Makefile|here]] )+<code bash> 
 +FILES="files
 +</code>
  
-Example syntax: +The ''files'' directory should be placed in the Image Builder root directory where you issue the make command, otherwise specify an absolute/full path.
-<code>make image PROFILE=XXX PACKAGES="pkg1 pkg2 pkg3 -pkg4 -pkg5 -pkg6" FILES=files/</code>+
  
-See the sections below for a more in-depth explanation. After the make command is finished, the generated images are stored in the bin///device-architecture// directory, just like if you were compiling them.+It is strongly recommended to use [[docs:guide-developer:uci-defaults|uci-defaults]] to incrementally integrate only the required customization. 
 +This helps minimize conflicts with auto-generated settings which can change between versions.
  
-==== make help ==== +see[[:docs:guide-user:additional-software:imagebuilder#restricting_root_access|uci-default_example]]
-<code>Available Commands: +
-        help  This help text +
-        info  Show a list of available target profiles +
-        clean Remove images and temporary build files +
-        image Build an image (see below for more information).+
  
-Building images: +==== Building image ==== 
-        By default 'make image' will create an image with the default +After you select the appropriate profile, packages and custom files, pass it to the ''make image'' command.
-        target profile and package setYou can use the following parameters +
-        to change that:+
  
-        make image PROFILE="<profilename># override the default target profile +<code bash> 
-        make image PACKAGES="<pkg1> [<pkg2> [<pkg3> ...]]# include extra packages +make image 
-        make image FILES="<path>" # include extra files from <path> +PROFILE="profile-name\ 
-        make image BIN_DIR="<path>" # alternative output directory for the images +PACKAGES="pkg1 pkg2 pkg3 -pkg4 -pkg5 -pkg6\ 
-        make image EXTRA_IMAGE_NAME="<string>" # Add this to the output image filename (sanitized) +FILES="files" \ 
-        make image DISABLED_SERVICES="<svc1> [<svc2> [<svc3> ..]]# Which services in /etc/init.d/ should be disabled+DISABLED_SERVICES="svc1 svc2 svc3" 
 +</code>
  
-Print manifest: +After the make command is finished, the generated images are stored in the bin///device-architecture// directory, just like if you were compiling them.
-        List "all" packages which get installed into the image. +
-        You can use the following parameters:+
  
-        make manifest PROFILE="<profilename>" # override the default target profile +The built image will be found under the subdirectory ''./bin/targets/<target>/generic'' or look inside .''/build_dir/'' for a files ''*-squashfs-sysupgrade.bin'' and ''*-squashfs-factory.bin'' (e.g. ''/build_dir/target-mips_24kc_musl/linux-ar71xx_tiny/tmp/openwrt-18.06.2-ar71xx-tiny-tl-wr740n-v6-squashfs-factory.bin'') 
-        make manifest PACKAGES="<pkg1> [<pkg2> [<pkg3> ...]]# include extra packages+ 
 +==== Cleaning up ==== 
 +To clean up temporary build files and generated images, use the ''make clean'' command. 
 + 
 +==== Examples ==== 
 +The following example shows: 
 +  * Creating the directory for the configuration files. 
 +  * Using ''scp'' to transfer ''uci'' configuration files from a WL500GP router to the ''files/etc/config'' directory. 
 +  * Generating an image for WL500GP with custom packages and ''uci'' configuration files. 
 + 
 +<code bash> 
 +mkdir -p files/etc/config 
 +scp root@192.168.1.1:/etc/config/network files/etc/config/ 
 +scp root@192.168.1.1:/etc/config/wireless files/etc/config/ 
 +scp root@192.168.1.1:/etc/config/firewall files/etc/config/ 
 +make image \ 
 +PROFILE="wl500gp"
 +PACKAGES="nano openvpn -ppp -ppp-mod-pppoe"
 +FILES="files"
 +DISABLED_SERVICES="dnsmasq firewall odhcpd"
 </code> </code>
  
 +===== 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/day(s) upstream packages may be in an inconsistent state especially on master/snapshot
 +  - Verify you have a supported OS, prerequisites, file system and path naming
  
-The built image will be found under the subdirectory ''./bin/targets/<target>/generic'' or look inside .''/build_dir/'' for a files ''*-squashfs-sysupgrade.bin'' and ''*-squashfs-factory.bin'' (e.g. ''/build_dir/target-mips_24kc_musl/linux-ar71xx_tiny/tmp/openwrt-18.06.2-ar71xx-tiny-tl-wr740n-v6-squashfs-factory.bin''+===== Extras ===== 
-==== PROFILE Variable ===== +The topics below go beyond simple usage and aimed at developers and advanced users.
-Syntax:<code>$ make image PROFILE=NAME_OF_PROFILE</code>+
  
-=== Pre-defined Profiles === +==== Detailed help ==== 
-Run ''make info'' to obtain a list of defined profiles+See also: [[https://github.com/openwrt/openwrt/blob/master/target/imagebuilder/files/Makefile|ImageBuilder makefile]] 
-Example output from ''make info'' is listed below.+ 
 +Getting detailed help:
  
-== ar71xx-generic Profiles == 
 <code> <code>
 +# make help
 +
 +Available Commands:
 + help: This help text
 + info: Show a list of available target profiles
 + clean: Remove images and temporary build files
 + image: Build an image (see below for more information).
 +
 +Building images:
 + By default 'make image' will create an image with the default
 + target profile and package set. You can use the following parameters
 + to change that:
 +
 + make image PROFILE="<profilename>" # override the default target profile
 + make image PACKAGES="<pkg1> [<pkg2> [<pkg3> ...]]" # include extra packages
 + make image FILES="<path>" # include extra files from <path>
 + make image BIN_DIR="<path>" # alternative output directory for the images
 + make image EXTRA_IMAGE_NAME="<string>" # Add this to the output image filename (sanitized)
 + make image DISABLED_SERVICES="<svc1> [<svc2> [<svc3> ..]]" # Which services in /etc/init.d/ should be disabled
 + make image ADD_LOCAL_KEY=1 # store locally generated signing key in built images
 +
 +Print manifest:
 + List "all" packages which get installed into the image.
 + You can use the following parameters:
 +
 + make manifest PROFILE="<profilename>" # override the default target profile
 + make manifest PACKAGES="<pkg1> [<pkg2> [<pkg3> ...]]" # include extra packages
 + make manifest STRIP_ABI=1 # remove ABI version from printed package names
 +</code>
 +
 +==== Available profiles ====
 +Listing available profiles:
 +
 +<code>
 +# make info
 +
 Available Profiles: Available Profiles:
  
Line 167: Line 240:
 rp-n53: rp-n53:
     Asus RP-N53     Asus RP-N53
-    Packages: +    Packages:
 rt-n14u: rt-n14u:
     Asus RT-N14u     Asus RT-N14u
-    Packages: +    Packages:
 whr-1166d: whr-1166d:
     Buffalo WHR-1166D     Buffalo WHR-1166D
-    Packages: +    Packages:
 whr-300hp2: whr-300hp2:
     Buffalo WHR-300HP2     Buffalo WHR-300HP2
     Packages:     Packages:
--and many many more-+...
 </code> </code>
  
-After you find the appropriate profile pass it to the ''make image'' command:+==== Building the Image Builder with all packages inside ==== 
 +It is possible to use a buildroot to create your own Image Builder and integrate in it all packages so it will be able to generate images without downloading packages.
  
-For exampleif we wanted to generate a default image for for Asus RT-N14u (from above).+In the graphical configurationselect "**Build the OpenWrt Image Builder**" to build the image builder, then  select **Global Build Settings -> Select all packages by default**, save and exit. 
 +You can [[docs:guide-developer:toolchain:use-buildsystem#ignore_build_errors|ignore build errors]] if you encounter unmaintained packages that fail to compile, assuming this doesn't affect kernel and core dependencies.
  
-<code> +Don't call ''make defconfig'' or leave an old ''.config'' file in the path as ''Select all packages by default'' will only set the package selection to ''[m]'' for packages that are not already configured otherwise! ''make defconfig'' will set most packages to ''[n]'', i.e. //do not build//.
-make image PROFILE=rt-n14u +
-</code>+
  
-==== PACKAGES Variable ==== +==== Adding package repositories ==== 
-The ''PACKAGES'' variable allows to include and/or exclude packages in the firmware imageBy 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.+The Image Builder you download from the OpenWrt pages is already configured to download any non-default packages from official repositories. 
 +The package sources are configured in the ''repositories.conf'' file in the extracted directory. 
 +Sources are specified in //opkg// native config format. 
 +This can be either the official package repositories or custom generated repositories.
  
-Syntax:<code>$ make image PACKAGES="pkg1 pkg2 pkg3 -pkg4 -pkg5 -pkg6"</code> +An example of the contents of the ''repositories.conf'' from the **openwrt-imagebuilder-18.06.0-rc2-ramips-mt7621.Linux-x86_64.tar.xz**:
-The example above will include pkg1, pkg2, pkg3, and exclude pkg4, pkg5, pkg6, note the "-" before each excluded package.+
  
-You don't need to list all dependencies of the packages you need in this list, the Image Generator uses ''opkg'' to resolve automatically the package dependencies and install other required packages.+<code bash> 
 +## Place your custom repositories herethey must match the architecture and version. 
 +# src/gz %n http://downloads.openwrt.org/releases/18.06.0-rc2 
 +# src custom file:///usr/src/openwrt/bin/ramips/packages
  
-**Tip:** The list of currently installed packages on your device can be obtained with the command below+## Remote package repositories 
-<code>echo $(opkg list_installed | awk '{ print $1 }')</code>+src/gz openwrt_core http://downloads.openwrt.org/releases/18.06.0-rc2/targets/ramips/mt7621/packages 
 +src/gz openwrt_base http://downloads.openwrt.org/releases/18.06.0-rc2/packages/mipsel_24kc/base 
 +src/gz openwrt_luci http://downloads.openwrt.org/releases/18.06.0-rc2/packages/mipsel_24kc/luci 
 +src/gz openwrt_packages http://downloads.openwrt.org/releases/18.06.0-rc2/packages/mipsel_24kc/packages 
 +src/gz openwrt_routing http://downloads.openwrt.org/releases/18.06.0-rc2/packages/mipsel_24kc/routing 
 +src/gz openwrt_telephony http://downloads.openwrt.org/releases/18.06.0-rc2/packages/mipsel_24kc/telephony
  
-<WRAP center round important 60%> +## This is the local package repository, do not remove! 
-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. +src imagebuilder file:packages 
-</WRAP>+</code>
  
-==== FILES Variable ==== +The ''repositories.conf'' in an imagebuilder you compile from source will lack the "Remote package repositories" links.
-The ''FILES'' variable allows custom configuration files to be included in images built with Image Generator. 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: +If you want to add a custom local repository, copy the ''%%src custom file:///usr/src/openwrt/bin/ramips/packages%%'' line and modify it to point to the local folder where you have your packages and package lists ([[https://downloads.openwrt.org/releases/21.02.3/targets/ramips/mt7621/packages/Packages|example package list]]). 
-<code>$ make image FILES=files/</code>+If you have problems with using you local repository because the "Signature check failed" then remove the line ''option check_signature'' from ''repositories.conf''
  
-**Note:** The ''files/'' folder is best in the imagebuilder root folder ( where you issue the make command ) otherwise it is best to use an absolute ( full ) path.+If you have custom repositories online, copy and modify the ''%%src/gz reboot http://downloads.openwrt.org/snapshots%%'' line instead.
  
 +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.
  
-==== Examples ==== +==== Restricting root access ==== 
-The following example shows:+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.
  
-  -Creating the directory for the configuration files +<code bash> 
-  -Using ''scp'' to transfer ''uci'' configuration files from a WL500GP router to the ''files/etc/config'' directory +mkdir -files/etc/uci-defaults 
-  -Generating an image for WL500GP with custom packages and ''uci'' configuration files +cat << "EOF" > files/etc/uci-defaults/99-custom 
- +USER_NAME="admin" 
-<code>mkdir -p files/etc/config +USER_SSHPUB="SSH_PUBLIC_KEY" 
-scp root@192.168.1.1:/etc/config/network files/etc/config+USER_SHELL="/bin/ash" 
-scp root@192.168.1.1:/etc/config/wireless files/etc/config+SUDO_USER="root
-scp root@192.168.1.1:/etc/config/firewall files/etc/config+SUDO_GROUP="sudo" 
-make image PROFILE=wl500gp PACKAGES="nano openvpn -ppp -ppp-mod-pppoeFILES=files/+groupadd -r "${SUDO_GROUP}" 
 +useradd -m -G "${SUDO_GROUP}" -s "${USER_SHELL}" "${USER_NAME}" 
 +passwd -l "${SUDO_USER}" 
 +cat << EOI > /etc/sudoers.d/00-custom 
 +%${SUDO_GROUP} ALL=(ALL) ALL 
 +EOI 
 +USER_HOME="$(eval echo ~"${USER_NAME}")" 
 +mkdir -p "${USER_HOME}"/.ssh 
 +cat << EOI > "${USER_HOME}"/.ssh/authorized_keys 
 +${USER_SSHPUB} 
 +EOI 
 +uci set dropbear.@dropbear[0].PasswordAuth="0" 
 +uci set dropbear.@dropbear[0].RootPasswordAuth="0" 
 +uci commit dropbear 
 +/etc/init.d/dropbear restart 
 +EOF 
 +make image 
 +FILES="files"
 +PACKAGES="nano shadow sudo"
 </code> </code>
  
-===== Cleanup ===== +==== Adding/modifying profiles ====
-To clean up temporary build files and generated images, use the **make clean** command.+
  
-====== Advanced Topics ====== +<WRAP important> 
-The topics below go beyond simple usage and aimed at developers and advanced users+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 
 +</WRAP>
  
-===== Adding/Modifying Profiles ===== +The image building is tied to the profile names. 
-The image generation is tied to the profile names. 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 the /tmp directory to get modified package selection from profiles to work+Remove the ''/tmp'' directory to properly apply the modified package selection from profiles.
  
 The location of the profiles for the pre-compiled package for //brcm47xx-for-Linux-i686// was //target/linux/brcm47xx/profiles/// The location of the profiles for the pre-compiled package for //brcm47xx-for-Linux-i686// was //target/linux/brcm47xx/profiles///
  
-Remarkably, all that needs to be done to add a new profile, is to add a new file to the //profiles// directory. //While this may have been the case in earlier releases, for 17.01, it appears that manual editing of ''.targetinfo'' is also required.//+Remarkably, all that needs to be done to add a new profile, is to add a new file to the //profiles// directory. 
 +//While this may have been the case in earlier releases, for 17.01, it appears that manual editing of ''.targetinfo'' is also required.//
  
-Here is what the //profiles/100-Broadcom-b43.mk// profile file looks like:  +Here is what the //profiles/100-Broadcom-b43.mk// profile file looks like:
  
-<WRAP> +<code bash>
-<code>+
 define Profile/Broadcom-b43 define Profile/Broadcom-b43
-  NAME:=Broadcom BCM43xx WiFi (default) + NAME:=Broadcom BCM43xx WiFi (default) 
-  PACKAGES:=kmod-b43 kmod-b43legacy+ PACKAGES:=kmod-b43 kmod-b43legacy
 endef endef
  
Line 254: Line 357:
 $(eval $(call Profile,Broadcom-b43)) $(eval $(call Profile,Broadcom-b43))
 </code> </code>
-</WRAP> 
  
-Alternately edit the hidden .profile.mk file at the top level directory of the image builder (e.g. me@mymachine:~/openwrt-imagebuilder-versxxx-at91-sam9x-.Linux-x86_64#and manually add the names of the desired packages to be added to the output image. An "ls -a" will reveal the files hidden in the various directories. +Alternately edit the hidden .profile.mk file at the top level directory of the image builder and manually add the names of the desired packages to be added to the output image. 
 +An "ls -a" will reveal the files hidden in the various directories.
  
-===== Remove useless files from firmware ===== +==== Removing useless files from firmware ==== 
-<WRAP center round important 60%>+<WRAP important>
 This is not a standard feature of the Image Builder. This is not a standard feature of the Image Builder.
  
-It is highly recommended that you test file removal prior to incorporating such changes at the image builder level or that you have low level means to recover a device before attempting this type of mod. As bricking / non booting may result. +It is highly recommended that you test file removal prior to incorporating such changes at the image builder level or that you have low level means to recover a device before attempting this type of mod, as bricking / non booting may result.
  
 Note that it requires patching of the ''Makefile'' Note that it requires patching of the ''Makefile''
 +
 +It is based on older Chaos Calmer era code... and not applicable to modern ImageBuilders but useful as a reference...
 </WRAP> </WRAP>
  
-1. Create file 'files_remove' with full filenames: +Create file ''files_remove'' with full filenames: 
-<code>+ 
 +<code bash>
 /lib/modules/3.10.49/ts_bm.ko /lib/modules/3.10.49/ts_bm.ko
 /lib/modules/3.10.49/nf_nat_ftp.ko /lib/modules/3.10.49/nf_nat_ftp.ko
Line 275: Line 381:
 </code> </code>
  
-2. Patch Makefile +Patch Makefile
-<code bash>+ 
 +<code diff>
  ifneq ($(USER_FILES),)  ifneq ($(USER_FILES),)
   $(MAKE) copy_files   $(MAKE) copy_files
Line 285: Line 392:
 + @echo Remove useless files + @echo Remove useless files
 + +
-+ while read filename; do ++ while read filename; do \ 
-+     rm -rfv "$(TARGET_DIR)$$filename"; \++     rm -rfv "$(TARGET_DIR)$$filename"; \
 + done < $(FILES_REMOVE); + done < $(FILES_REMOVE);
 +endif +endif
Line 294: Line 401:
 </code> </code>
  
-3. Rebuild firmware +Rebuild firmware:
-<code> +
-# make image \ +
-    PROFILE=tlwr841 \ +
-    PACKAGES="igmpproxy ip iptraf kmod-ipt-nathelper-extra openvpn-polarssl tcpdump-mini -firewall -ip6tables -kmod-ip6tables -kmod-ipv6 -odhcp6c -ppp -ppp-mod-pppoe"+
-    FILES_REMOVE="files_remove" +
-</code>+
  
- +<code bash> 
-===== Building the Image Generator with all packages inside ===== +make image \ 
-It is possible to build the Image Generator and integrate in it all packages so it will be able to generate images without downloading packages: +PROFILE="tlwr841\ 
- +PACKAGES="igmpproxy ip iptraf kmod-ipt-nathelper-extra openvpn-polarssl tcpdump-mini -firewall -ip6tables -kmod-ip6tables -kmod-ipv6 -odhcp6c -ppp -ppp-mod-pppoe" \ 
-In the graphical configuration, select "**Build the OpenWrt Image Builder**to build the image builder, then  select **Global Build Settings** -> **Select all packages by default**, save and exit. +FILES_REMOVE="files_remove"
-Then build the image, including ''IGNORE_ERRORS=1'' as there might be unmaintained packages that fail to compile. +
- +
-Enabling ''IGNORE_ERRORS=1'' should only be done **once the kernel and required packages are known to compile successfully.** +
- +
-<code>make IGNORE_ERRORS=1+
 </code> </code>
- 
-**Note:** Don't call ''make defconfig'' or leave an old ''.config'' file in the path as ''Select all packages by default'' will only set the package selection to ''[m]'' for packages that are not already configured otherwise!(''make defconfig'' will set most packages to ''[n]'', i.e. //do not build//.) 
- 
  • Last modified: 2024/09/20 19:32
  • by lessload