Opkg package manager

Like most Linux distributions (or mobile device operating systems like say Android or iOS), the functionality of the system can be upgraded rather significantly by downloading and installing pre-made packages from package repositories (local or on the Internet).

The opkg utility is the lightweight package manager used for this job. Opkg is a fork of ipkg, the package manager used in NSLU2's Optware^{(archive link)}, which is designed to add software to stock firmware of embedded devices.

Opkg is a full package manager for the root file system, including kernel modules and drivers, while ipkg is just a way to add software to a separate directory (e.g. /opt).

Opkg is sometimes called Entware, as it is also the package manager used by the Entware repository for embedded devices (itself a fork of OpenWrt's community packages repository).

The package manager opkg attempts to resolve dependencies with packages in the repositories - if this fails, it will report an error and abort the installation of that package.

Missing dependencies with third-party packages are probably available from the source of the package.
To ignore dependency errors, pass the --force-depends flag.

If you are using a snapshot / trunk / bleeding edge version, installing packages may fail if the package in the repository is for a newer kernel version than the kernel version you have.
In this case, you will get the error message “Cannot satisfy the following dependencies for…”.
For such usage of OpenWrt firmware, it's warmly recommended to use the Image Builder to make a flashable image containing all packages you need.

When on trunk/snapshot, kernel and kmod packages are flagged as hold, the opkg upgrade command won't attempt to update them.

# opkg
opkg must have one sub-command argument:
usage: opkg [options...] sub-command [arguments...]
where sub-command is one of:

You can use glob patterns.

# Install a package
opkg update
opkg install <package>
 
# List packages
opkg list
 
# Display package information
opkg info <package>

You can make use of glob patterns directly and also write a little shell script to use regular expressions and otherwise further process information. Use a pipeline and grep, or awk, or sed to filter that output:

opkg list | grep -e <pattern1> -e <pattern2>
opkg list | awk -e '/<pattern>/{print $0}'
opkg info kmod-nf-\* | awk -e '/length/{print $0}'
opkg list-installed | awk -e '{print $1}' | tr '\n' ' '
for pkg in <package1> <package2> <package3>; do opkg info ${pkg}; done
opkg depends dropbear

# Upgrade all installed packages
opkg list-upgradable | cut -f 1 -d ' ' | xargs opkg upgrade

The main configuration file is /etc/opkg.conf. It could look like this:

dest root /
dest ram /tmp
lists_dir ext /var/opkg-lists
option overlay_root /overlay

As you can see, it sets default folders:

• default root directory (default / )
• default ram disk (default /tmp )
• default folder to store package lists (default /var/opkg-lists, still a ram disk)
• what is the overlay directory (default /overlay)

Most of these options must be left to default, or have no real reason to be changed.

You might want to change the lists_dir ext /var/opkg-lists to lists_dir ext /path/on/disk if your device has 32 MiB or less of RAM and you expanded your firmware's storage space in an external drive, so you can use opkg without causing Out Of Memory errors.

This file is accessible and can be modified from Luci Web interface too, Click on Services then on Software. Click on Configuration tab.

Feeds are set in /etc/opkg/distfeeds.conf:

src/gz reboot_core http://downloads.lede-project.org/snapshots/targets/ramips/mt7620/packages
src/gz reboot_base http://downloads.lede-project.org/snapshots/packages/mipsel_24kc/base
src/gz reboot_telephony http://downloads.lede-project.org/snapshots/packages/mipsel_24kc/telephony
src/gz reboot_packages http://downloads.lede-project.org/snapshots/packages/mipsel_24kc/packages
src/gz reboot_routing http://downloads.lede-project.org/snapshots/packages/mipsel_24kc/routing
src/gz reboot_luci http://downloads.lede-project.org/snapshots/packages/mipsel_24kc/luci

There is also another file for custom feeds called /etc/opkg/customfeeds.conf:

# add your custom package feeds here
#
# src/gz example_feed_name http://www.example.com/path/to/files

Both files are accessible and can be modified from Luci Web interface too, Click on Services then on Software. Click on Configuration tab, then scroll down.

You can configure opkg to fetch the packages locally:

src/gz local file:///path/to/packagesDirectory

OpenWrt uses multiple repositories, where every repository requires a unique identifier. It is logical to use their original names, e.g.:

...
src/gz base file:///path/to/packages/directory/packages/base
src/gz luci file:///path/to/packages/directory/packages/luci
src/gz packages file:///path/to/packages/directory/packages/packages
src/gz oldpackages file:///path/to/packages/directory/packages/oldpackages
... etc ...

By default, opkg only allows packages with the architecture all (= architecture independent) and the architecture of the installed target. In order to download and install packages for a foreign target architecture, the list of allowed architectures can be overridden in /etc/opkg.conf with the use of arch options:

arch all 100
arch brcm4716 200
arch brcm47xx 300

This example would allow installing brcm47xx packages (compiled to run on brcm47xx family of SoC/devices) on the brcm4716 (a specific SoC) target. The number specifies a priority index which is used by opkg to determine which package to prefer in case it is available in multiple architectures.

OpenWrt 21.02:

# Configure profile
mkdir -p /etc/profile.d
cat << "EOF" > /etc/profile.d/custom.sh
export https_proxy=http://proxy.example.org:8080/
EOF
. /etc/profile
 
# Workaround
sed -i -e "s/https/http/" /etc/opkg/distfeeds.conf

To use opkg through a proxy, add the following to /etc/opkg.conf:

option http_proxy http://proxy.example.org:8080/
option ftp_proxy ftp://proxy.example.org:2121/

Use the options below to authenticate against the proxy server:

option proxy_user xxxx
option proxy_passwd xxxx

Alternatively, a username and password may be provided as part of the URL if busybox wget is installed:

option http_proxy http://username:password@proxy.example.org:8080/
option ftp_proxy http://username:password@proxy.example.org:2121/

Authentication currently fails when using uclient-fetch as wget due to Proxy-Authorization not yet being implemented.

If you are running apt-cacher-ng and want to use that for OpenWRT, you may experience problems downloading .sig files through apt-cacher-ng. In that case put the following line in your acng.conf file:

VfilePatternEx: |\.sig$

# Save the script
cat << "EOF" > opkg-update.sh
#!/bin/sh
rm -f -R /tmp/opkg-lists
mkdir -p /tmp/opkg-lists
while read TYPE REPO URL
do
wget -O /tmp/opkg-lists/"${REPO}".gz "${URL}"/Packages.gz
wget -O /tmp/opkg-lists/"${REPO}".sig "${URL}"/Packages.sig
gunzip -k /tmp/opkg-lists/"${REPO}".gz
usign -V -P /etc/opkg/keys -m /tmp/opkg-lists/"${REPO}" 2>&1 \
| grep -e "^OK$" \
&& mv -f /tmp/opkg-lists/"${REPO}".gz /tmp/opkg-lists/"${REPO}"
done < /etc/opkg/distfeeds.conf
EOF
chmod +x opkg-update.sh
 
# Run the script
./opkg-update.sh

Remove partly installed packages and their dependencies if opkg runs out of space during a transaction.

# Save the script
cat << "EOF" > opkg-rm-pkg-deps.sh
#!/bin/sh
opkg update
URL="$(opkg --force-space --noaction install "${@}" \
| sed -n -e "/^Downloading\s*/s///p")"
rm -f /usr/lib/opkg/lock
for URL in ${URL}
do FILE="$(wget -q -O - "${URL}" \
| tar -O -x -z ./data.tar.gz \
| tar -t -z \
| sort -r \
| sed -e "s|^\.|/overlay/upper|")"
for FILE in ${FILE}
do if [ -f "${FILE}" ]
then rm -f "${FILE}"
elif [ -d "${FILE}" ]
then rmdir "${FILE}"
fi
done
done
EOF
chmod +x opkg-rm-pkg-deps.sh

# Run the script
./opkg-rm-pkg-deps.sh package_name
 
# Reboot to make the free space visible
reboot

There may be use cases where having a package repository on the device itself is advantageous:

• Unreliable WANs, where the connectivity upstream of the device to a remote repository goes down for an unacceptable period of time.
• Bandwidth Caps, where the connectivity upstream of the device to a remote repository has a limited amount of data that can be fetched before the connectivity is throttled or goes down until the next period where the cap resets.
• A repository with customization; built from source, which isn't available from remote repositories.
• The device acts as a reference device for other systems, to ensure that the package versions across the devices local to the network remain consistent.

Set up a local repository for your target. Assuming about 2-3 GB of free space is available.

# Install packages
opkg update
opkg install rsync
 
# Save the script
cat << "EOF" > local-repo-sync.sh
#!/bin/sh
. /etc/os-release
REPO_LOCAL="file://${1:-/${ID}}/"
REPO_URL="https://downloads.${HOME_URL#*//}"
case "${VERSION_ID}" in
(snapshot) REPO_DIR="downloads/snapshots" ;;
(*) REPO_DIR="downloads/releases/${VERSION_ID}" ;;
esac
REPO_CORE="${REPO_DIR}/targets/${OPENWRT_BOARD}"
REPO_PKGS="${REPO_DIR}/packages/${OPENWRT_ARCH}"
for REPO_DIR in "${REPO_CORE}" "${REPO_PKGS}"
do mkdir -p "${REPO_LOCAL#*//}${REPO_DIR#*/}"
rsync --bwlimit="8M" --del -r -t -v \
"${REPO_URL/https/rsync}${REPO_DIR}/" \
"${REPO_LOCAL#*//}${REPO_DIR#*/}/"
done
EOF
chmod +x local-repo-sync.sh
 
# Run the script
./local-repo-sync.sh /openwrt
 
# Configure Opkg to use local repo
. /etc/os-release
REPO_LOCAL="file:///${ID}/"
REPO_URL="https://downloads.${HOME_URL#*//}"
sed -i -e "s|${REPO_URL}|${REPO_LOCAL}|" /etc/opkg/distfeeds.conf
 
# Share the repository on the LAN
ln -f -s ${REPO_LOCAL#*//} /www/${ID}
 
# Configure Opkg on the clients
. /etc/os-release
REPO_LOCAL="http://192.168.1.1/${ID}/"
REPO_URL="https://downloads.${HOME_URL#*//}"
sed -i -e "s|${REPO_URL}|${REPO_LOCAL}|" /etc/opkg/distfeeds.conf

See also: How to mirror

Due to its history (fork of ipkg), opkg can specify a destination different than root for package installation, but since most packages don't support this natively, it's more a curiosity than actually useful.

The default /etc/opkg.conf actually contains three destinations:

dest root /
dest ram /tmp
dest mnt /mnt

The format of destination lines is simply the keyword dest, followed by a name for this destination (this can be anything), followed by a filesystem location. Any destination that has been thus configured can then be specified on the opkg command line like this:

opkg -d destination_name install somepackage

The dest argument must refer to one of the defined destinations in /etc/opkg.conf, e.g. -d ram to install packages to /tmp/.

If you want to install kernel modules on any other destination than root, you might want to read this first: https://dev.openwrt.org/ticket/10739