OPKG component description

The opkg package manager is designed to extend the capabilities of Keenetic devices by installing additional software packages. Using opkg, advanced users can install and update modules not included in the device's basic firmware, allowing them to flexibly configure the router's functionality for specific tasks.

This article describes the principles of using opkg in KeeneticOS, including the installation procedure, methods for connecting external storage, and recommendations for using packages from the repository.

The Open Package support component must be installed on the device to use open packages.

The component will:

add opkg configuration commands,
mount a USB filesystem to /opt,
inflate *.ipk and *.tar.gz files from the /opt/install directory,
execute hook scripts.

Configuration

The opkg disk command is used to specify the /opt filesystem. The filesystem can be identified by either UUID or a volume label. For example,

(config)> opkg disk OPT_LABEL:
Opkg::Manager: Disk is set to: OPT_LABEL.
(config)> system configuration save

NTFS and EXT2/3 filesystems are supported. Once the opkg disk is configured and the storage is attached, the opkg component will:

Mount the OPT_LABEL filesystem to /opt.
If the /opt/install directory exists, inflate all /opt/install/*.ipk files to /opt. This unpack should be finished in 120 seconds or it will be finished by timeout.
Execute /opt/etc/initrc.

Hook Scripts

Hook scripts are located in:

/opt/etc/initrc — default startup script (can be defined via opkg initrc command),
/opt/etc/ndm/*.d/ — event handlers.

Script directories and environment variables are described in specific sections below.

PATH and LD_LIBRARY_PATH variables are predefined for selection of executables and dynamic libraries from /opt:

PATH=/opt/bin:/opt/sbin:/opt/usr/bin:/opt/usr/sbin:/bin:/sbin:/usr/bin:/usr/sbin
LD_LIBRARY_PATH=/opt/lib:/opt/usr/lib:/lib:/usr/lib

The /opt prefix is always implied in the hook script shebang. That is, both #!/bin/sh and #!/opt/bin/sh will execute the /opt/bin/sh interpreter.

There's a 24-second timeout on every script to be executed.

All hook scripts started in one queue, i.e. while /opt/etc/ndm/wan.d/01-one.sh is still running, no any other scripts will be started neither from /opt/etc/ndm/wan.d/ nor from /opt/etc/ndm/netfilter.d/.

initrc

The initialization script /opt/etc/initrc is executed after /opt is mounted. It can execute some other init scripts, such as /opt/etc/init.d/* to start background processes. If /opt/etc/initrc is missing, the OPKG component will execute /opt/etc/init.d/* in alphabetic order.

For example, dropbear startup script might be:

#!/bin/sh

if [ ! -d /opt/etc/dropbear ]; then
    mkdir /opt/etc/dropbear
fi

if [ ! -f /opt/etc/dropbear/dropbear_dss_host_key ]; then
    dropbearkey -t dss -f /opt/etc/dropbear/dropbear_dss_host_key
fi

if [ ! -f /opt/etc/dropbear/dropbear_rsa_host_key ]; then
    dropbearkey -t rsa -f /opt/etc/dropbear/dropbear_rsa_host_key
fi

dropbear

To make it compatible with Sys-V-like init systems, /opt/etc/initrc and /opt/etc/init.d scripts are called with the start command line argument. When the user wants to eject the /opt storage, /opt/etc/initrc is called with the stop argument.

ndm/wan.d

/opt/etc/ndm/wan.d/ event scripts are executed once a new Internet connection is available.

1st Parameter	Description
`start`	Internet connection established
`stop`	Internet connection terminated

Variable	Description
`$interface`	WAN interface, such as `ppp0`
`$address`	Interface IP address
`$mask`	Interface subnet mask
`$gateway`	WAN gateway IP address

When the internet connection is down, the wan.d scripts are executed with all the above variables undefined.

If the internet connection has been established before mounting /opt, the wan.d scripts are executed right after initrc.

ndm/user.d

/opt/etc/ndm/user.d scripts are executed when /etc/passwd and /etc/group are refreshed by the core system. Add scripts to user.d if you need to modify /etc/passwd or /etc/group. Otherwise, any changes to these files will be overwritten.

Variable	Description
`$user`	User name with `OptWare` access, if added through the core system

When a user is deleted, the user.d scripts are executed with an undefined $user.

For example, you can create home directories using the user.d hook as follows:

#!/bin/sh

home=/opt/home

[ -z "$user" ] && exit 0       # $user is undefined
[ -d $home/$user ] && exit 0   # home already exists

if mkdir -p $home/$user; then
    chmod 0755 $home
    chmod 0700 $home/$user
    chown $user $home/$user
fi

ndm/netfilter.d

/opt/etc/ndm/netfilter.d scripts are executed when the system rewrites a netfilter table. The netfilter.d hooks can modify the table using iptables. The $table and $type variables should be checked to prevent rule duplicates.

Variable	Description
`$type`	netfilter protocol, such as `iptables` for IPv4 or `ip6tables` for IPv6
`$table`	netfilter table, such as `filter`, `nat` or `mangle`

For example, you can add some mangle rules as follows:

#!/bin/sh

[ "$type" == "ip6tables" ] && exit 0   # check the protocol type in backward-compatible way
[ "$table" != "mangle" ] && exit 0   # check the table name

iptables -A PREROUTING -i br0 -t mangle -p tcp --dport 22 -j MARK --set-mark 1
iptables -A PREROUTING -i br0 -t mangle -p tcp --dport 23 -j MARK --set-mark 1

ndm/usb.d

/opt/etc/ndm/usb.d scripts are executed when a USB dongle is attached or detached.

1st Parameter	Description
`start`	USB device attached
`stop`	USB device detached

The following environment variables are defined to let you identify the dongle.

Variable	Description	Example
`$usb_device`	Path to the `/proc/bus/usb` device	`/proc/bus/usb/002/001`
`$usb_devname`	Name of device in `/proc/bus/usb`	`bus/usb/002/001`
`$usb_devpath`	Path in sysfs	`/devices/platform/xhci-hcd/usb2`
`$usb_model`	USB model ID	`0003`
`$usb_port`	USB port number	`2`
`$usb_vendor`	USB vendor ID	`1d6b`

Any device connected before the execution of the opkg init script will trigger these callback scripts scheduled to be run at the execution of the OPKG init script.

ndm/fs.d

/opt/etc/ndm/fs.d scripts are called when the filesystem is mounted or preparing to be unmounted or unexpectedly ejected.

1st Parameter	Description
`start`	Filesystem is mounted
`stop`	Filesystem is preparing to be unmounted or unexpectedly ejected

Filesystem type can be any of: VFAT, EXFAT, NTFS, EXT2, EXT3, EXT4 or HFSP.

Variable	Description	Example
`$type`	Filesystem type	`EXT2`
`$name`	Filesystem ID	`583a7335-6ef8-460b-a4c1-43a2e5c70e71:`
`$label`	Filesystem / partition label	`SecondPart`
`$directory`	Filesystem mount directory (absolute path)	`/tmp/mnt/SecondPart`

Any filesystem mounted before execution of the OPKG init script will trigger this callback scripts, scheduled to be run at the execution of OPKG init script.

ndm/time.d

/opt/etc/ndm/time.d scripts are called when the system time is changed (synchronized via NTP).

ndm/button.d

/opt/etc/ndm/button.d scripts are called when FN Button, and/or WPS Button(s) has been pressed.

Variable	Description	Example
`$button`	Which button has been pressed	`WLAN`
`$action`	Type of click	`click`, `double-click` or `hold`

You have to configure some details from the web interface first.

ndm/schedule.d

/opt/etc/ndm/schedule.d scripts are called with scheduled events (if schedules are defined via CLI).

1st Parameter	Description
`start`	Start of scheduled task
`stop`	End of scheduled task