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 viaopkg 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 |
---|---|
| Internet connection established |
| Internet connection terminated |
Variable | Description |
---|---|
| WAN interface, such as |
| Interface IP address |
| Interface subnet mask |
| 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 name with |
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 |
---|---|
| netfilter protocol, such as |
| netfilter table, such as |
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 |
---|---|
| USB device attached |
| USB device detached |
The following environment variables are defined to let you identify the dongle.
Variable | Description | Example |
---|---|---|
| Path to the |
|
| Name of device in |
|
| Path in sysfs |
|
| USB model ID |
|
| USB port number |
|
| USB vendor ID |
|
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 |
---|---|
| Filesystem is mounted |
| 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 |
---|---|---|
| Filesystem type |
|
| Filesystem ID |
|
| Filesystem / partition label |
|
| Filesystem mount directory (absolute path) |
|
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 |
---|---|---|
| Which button has been pressed |
|
| Type of click |
|
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 of scheduled task |
| End of scheduled task |
The following environment variables are defined to let you identify the task details.
Variable | Description |
---|---|
| Name of schedule |
| Time (in seconds) taken for action |
ndm/neighbour.d
/opt/etc/ndm/neighbour.d
scripts are called with certain network neighbour events. Scripts are invoked with the first parameter($1
) == hook
.
The following environment variables are defined to let you identify the task details.
Variable | Description |
---|---|
| Unique ID of neighbour since boot |
| Neighbour action( |
| Type of update (if any): |
| Address family - |
ndm/ifcreated.d
/opt/etc/ndm/ifcreated.d
scripts are called when an NDM interface is created. Scripts are invoked with the first parameter($1
) == hook
.
The following environment variables are defined to let you identify the task details.
Variable | Description |
---|---|
| NDM interface ID |
| Linux-specific interface name |
ndm/ifdestroyed.d
/opt/etc/ndm/ifdestroyed.d
scripts are called when an NDM interface is removed. Scripts are invoked with the first parameter($1
) == hook
.
The following environment variables are defined to let you identify the task details.
Variable | Description |
---|---|
| NDM interface ID |
| Linux-specific interface name |
ndm/ifipchanged.d
/opt/etc/ndm/ifipchanged.d
scripts are called when the IPv4 address or subnet of an NDM interface is changed. Scripts are invoked with the first parameter($1
) == hook
.
The following environment variables are defined to let you identify the task details.
Variable | Description |
---|---|
| NDM interface ID |
| Linux-specific interface name |
| New IPv4 address |
| New IPv4 network mask |
| Interface current link status, can be |
| Interface current connection status, can be |
| Interface current status, can be |
| Interface current global priority, can be zero for non-global interfaces and > 0 when interface is global |
ndm/ifip6changed.d (since 4.0)
/opt/etc/ndm/ifip6changed.d
scripts are called when the IPv6 address or subnet of an NDM interface is changed. Scripts are invoked with the first parameter($1
) == hook
.
The following environment variables are defined to let you identify the task details.
Variable | Description |
---|---|
| NDM interface ID |
| Linux-specific interface name |
| IPv6 address |
| IPv6 network mask |
| Interface current link status, can be |
| Interface current connection status, can be |
| Interface current status, can be |
| Current change action, can be |
| Interface current global priority, can be zero for non-global interfaces and > 0 when interface is global |
ndm/ifstatechanged.d (obsoleted since 4.0, kept only for backwards compatibility)
/opt/etc/ndm/ifstatechanged.d
scripts are called when the status of an NDM interface is changed. Scripts are invoked with the first parameter($1
) == hook
.
The following environment variables are defined to let you identify the task details.
Variable | Description |
---|---|
| NDM interface ID |
| Linux-specific interface name |
| Interface current link status, can be |
| Interface current connection status, can be |
| Interface current status, can be |
| Source of changes, can be |
ndm/iflayerchanged.d (new and primary from 4.0)
/opt/etc/ndm/iflayerchanged.d
scripts are called when the status of an NDM interface layer state is changed. Scripts are invoked with the first parameter($1
) == hook
.
The following environment variables are defined to let you identify the task details.
Variable | Description |
---|---|
| NDM interface ID |
| Linux-specific interface name |
| Interface layer, can be |
| Interface layer current status, can be |
ndm/sms.d
/opt/etc/ndm/sms.d
scripts are called when SMS on UsbQmi interface is received. Scripts are invoked with the first parameter($1
) == hook
.
The following environment variables are defined to let you identify the task details.
Variable | Description |
---|---|
| NDM interface ID |
| SMS ID |
Actual content of SMS can be retrieved via ci/rci (ndmq / jq commands) using the supplied interface and message IDs.
ndm/pptp_vpn_up.d
/opt/etc/ndm/pptp_vpn_up.d
scripts are called when a user is connected to the PPTP VPN server. Scripts are invoked with the first parameter($1
) == hook
.
The following environment variables are defined to let you identify the task details.
Variable | Description |
---|---|
| User name |
| System interface (typically vpn*) |
| External IPv4 address of remote peer |
| IPv4 address of remote peer inside tunnel |
ndm/pptp_vpn_down.d
/opt/etc/ndm/pptp_vpn_down.d
scripts are called when a user is disconnected from the PPTP VPN server. Scripts are invoked with the first parameter($1
) == hook
.
The following environment variables are defined to let you identify the task details.
Variable | Description |
---|---|
| User name |
| System interface (typically sstp*) |
| External IPv4 address of remote peer |
| IPv4 address of remote peer inside tunnel |
ndm/l2tp_ipsec_vpn_up.d
/opt/etc/ndm/l2tp_ipsec_vpn_up.d
scripts are called when a user is connected to the L2TP/IPsec VPN server. Scripts are invoked with the first parameter($1
) == hook
.
The following environment variables are defined to let you identify the task details.
Variable | Description |
---|---|
$ndm_opkg_id | User name |
$iface | System interface (typically l2tp*) |
$remote | External IPv4 address of remote peer |
$local | IPv4 address of remote peer inside tunnel |
ndm/l2tp_ipsec_vpn_down.d
/opt/etc/ndm/l2tp_ipsec_vpn_down.d
scripts are called when a user is disconnected from the L2TP/IPsec VPN server. Scripts are invoked with the first parameter($1
) == hook
.
The following environment variables are defined to let you identify the task details.
Variable | Description |
---|---|
| User name |
| System interface (typically l2tp*) |
| External IPv4 address of remote peer |
| IPv4 address of remote peer inside tunnel |
ndm/vip_vpn_up.d
/opt/etc/ndm/vip_vpn_up.d
scripts are called when a user is connected to the Virtual IP VPN server. Scripts are invoked with the first parameter($1
) == hook
.
The following environment variables are defined to let you identify the task details.
Variable | Description |
---|---|
| User name |
| External IPv4 address of remote peer |
| IPv4 address of remote peer inside tunnel |
ndm/vip_vpn_down.d
/opt/etc/ndm/vip_vpn_down.d
scripts are called when a user is disconnected from the Virtual IP VPN server. Scripts are invoked with the first parameter($1
) == hook
.
The following environment variables are defined to let you identify the task details.
Variable | Description |
---|---|
| User name |
| External IPv4 address of remote peer |
| IPv4 address of the remote peer inside the tunnel |
ndm/openvpn-*.d
/opt/etc/ndm/openvpn-*.d/
scripts are called when OpenVPN
in NDMS executes a hook script (2.10+, only when ndm-mod-openvpn
is installed and configured).
List of scripts:
/opt/etc/ndm/openvpn-up.d/
/opt/etc/ndm/openvpn-tls-verify.d/
/opt/etc/ndm/openvpn-ipchange.d/
/opt/etc/ndm/openvpn-client-connect.d/
/opt/etc/ndm/openvpn-route-up.d/
/opt/etc/ndm/openvpn-client-disconnect.d/
/opt/etc/ndm/openvpn-down.d/
/opt/etc/ndm/openvpn-learn-address.d/
The meanings of scripts should be checked on the official OpenVPN man page (section SCRIPTING AND ENVIRONMENTAL VARIABLES).
All environmental variables set by OpenVPN itself (described here) are preserved as is and passed to the OPKG hook scripts. Scripts are invoked with the first parameter($1
) == hook
. All arguments from the original hook execution are passed as additional environment variables.
Variable | Description |
---|---|
| NDMS ID of interface, for example, |
| Count of arguments in the original hook invocation |
| Value of argument |