5 Utilities for interaction with the Linux system
11 Copyright 2008 Steven Barth <steven@midlink.org>
13 Licensed under the Apache License, Version 2.0 (the "License");
14 you may not use this file except in compliance with the License.
15 You may obtain a copy of the License at
17 http://www.apache.org/licenses/LICENSE-2.0
19 Unless required by applicable law or agreed to in writing, software
20 distributed under the License is distributed on an "AS IS" BASIS,
21 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
22 See the License for the specific language governing permissions and
23 limitations under the License.
28 local io = require "io"
29 local os = require "os"
30 local table = require "table"
31 local nixio = require "nixio"
32 local fs = require "nixio.fs"
33 local uci = require "luci.model.uci"
36 luci.util = require "luci.util"
37 luci.ip = require "luci.ip"
39 local tonumber, ipairs, pairs, pcall, type, next, setmetatable, require, select =
40 tonumber, ipairs, pairs, pcall, type, next, setmetatable, require, select
43 --- LuCI Linux and POSIX system utilities.
46 --- Execute a given shell command and return the error code
49 -- @param ... Command to call
50 -- @return Error code of the command
52 return os.execute(...) / 256
55 --- Execute a given shell command and capture its standard output
58 -- @param command Command to call
59 -- @return String containg the return the output of the command
62 --- Retrieve information about currently mounted file systems.
63 -- @return Table containing mount information
66 local k = {"fs", "blocks", "used", "available", "percent", "mountpoint"}
67 local ps = luci.util.execi("df")
79 for value in line:gmatch("[^%s]+") do
86 -- this is a rather ugly workaround to cope with wrapped lines in
89 -- /dev/scsi/host0/bus0/target0/lun0/part3
90 -- 114382024 93566472 15005244 86% /mnt/usb
96 for value in line:gmatch("[^%s]+") do
102 table.insert(data, row)
109 --- Retrieve environment variables. If no variable is given then a table
110 -- containing the whole environment is returned otherwise this function returns
111 -- the corresponding string value for the given name or nil if no such variable
115 -- @param var Name of the environment variable to retrieve (optional)
116 -- @return String containg the value of the specified variable
117 -- @return Table containing all variables if no variable name is given
118 getenv = nixio.getenv
120 --- Get or set the current hostname.
121 -- @param String containing a new hostname to set (optional)
122 -- @return String containing the system hostname
123 function hostname(newname)
124 if type(newname) == "string" and #newname > 0 then
125 fs.writefile( "/proc/sys/kernel/hostname", newname )
128 return nixio.uname().nodename
132 --- Returns the contents of a documented referred by an URL.
133 -- @param url The URL to retrieve
134 -- @param stream Return a stream instead of a buffer
135 -- @param target Directly write to target file name
136 -- @return String containing the contents of given the URL
137 function httpget(url, stream, target)
139 local source = stream and io.popen or luci.util.exec
140 return source("wget -qO- '"..url:gsub("'", "").."'")
142 return os.execute("wget -qO '%s' '%s'" %
143 {target:gsub("'", ""), url:gsub("'", "")})
147 --- Returns the system load average values.
148 -- @return String containing the average load value 1 minute ago
149 -- @return String containing the average load value 5 minutes ago
150 -- @return String containing the average load value 15 minutes ago
152 local info = nixio.sysinfo()
153 return info.loads[1], info.loads[2], info.loads[3]
156 --- Initiate a system reboot.
157 -- @return Return value of os.execute()
159 return os.execute("reboot >/dev/null 2>&1")
162 --- Returns the system type, cpu name and installed physical memory.
163 -- @return String containing the system or platform identifier
164 -- @return String containing hardware model information
165 -- @return String containing the total memory amount in kB
166 -- @return String containing the memory used for caching in kB
167 -- @return String containing the memory used for buffering in kB
168 -- @return String containing the free memory amount in kB
169 -- @return String containing the cpu bogomips (number)
171 local cpuinfo = fs.readfile("/proc/cpuinfo")
172 local meminfo = fs.readfile("/proc/meminfo")
174 local memtotal = tonumber(meminfo:match("MemTotal:%s*(%d+)"))
175 local memcached = tonumber(meminfo:match("\nCached:%s*(%d+)"))
176 local memfree = tonumber(meminfo:match("MemFree:%s*(%d+)"))
177 local membuffers = tonumber(meminfo:match("Buffers:%s*(%d+)"))
178 local bogomips = tonumber(cpuinfo:match("[Bb]ogo[Mm][Ii][Pp][Ss].-: ([^\n]+)")) or 0
179 local swaptotal = tonumber(meminfo:match("SwapTotal:%s*(%d+)"))
180 local swapcached = tonumber(meminfo:match("SwapCached:%s*(%d+)"))
181 local swapfree = tonumber(meminfo:match("SwapFree:%s*(%d+)"))
184 cpuinfo:match("system type\t+: ([^\n]+)") or
185 cpuinfo:match("Processor\t+: ([^\n]+)") or
186 cpuinfo:match("model name\t+: ([^\n]+)")
189 luci.util.pcdata(fs.readfile("/tmp/sysinfo/model")) or
190 cpuinfo:match("machine\t+: ([^\n]+)") or
191 cpuinfo:match("Hardware\t+: ([^\n]+)") or
192 luci.util.pcdata(fs.readfile("/proc/diag/model")) or
193 nixio.uname().machine or
196 return system, model, memtotal, memcached, membuffers, memfree, bogomips, swaptotal, swapcached, swapfree
199 --- Retrieves the output of the "logread" command.
200 -- @return String containing the current log buffer
202 return luci.util.exec("logread")
205 --- Retrieves the output of the "dmesg" command.
206 -- @return String containing the current log buffer
208 return luci.util.exec("dmesg")
211 --- Generates a random id with specified length.
212 -- @param bytes Number of bytes for the unique id
213 -- @return String containing hex encoded id
214 function uniqueid(bytes)
215 local rand = fs.readfile("/dev/urandom", bytes)
216 return rand and nixio.bin.hexlify(rand)
219 --- Returns the current system uptime stats.
220 -- @return String containing total uptime in seconds
222 return nixio.sysinfo().uptime
226 --- LuCI system utilities / network related functions.
228 -- @name luci.sys.net
231 --- Returns the current arp-table entries as two-dimensional table.
232 -- @return Table of table containing the current arp entries.
233 -- The following fields are defined for arp entry objects:
234 -- { "IP address", "HW address", "HW type", "Flags", "Mask", "Device" }
235 function net.arptable(callback)
236 local arp = (not callback) and {} or nil
238 if fs.access("/proc/net/arp") then
239 for e in io.lines("/proc/net/arp") do
241 for v in e:gmatch("%S+") do
247 ["IP address"] = r[1],
250 ["HW address"] = r[4],
267 local function _nethints(what, callback)
268 local _, k, e, mac, ip, name
269 local cur = uci.cursor()
273 local function _add(i, ...)
274 local k = select(i, ...)
276 if not hosts[k] then hosts[k] = { } end
277 hosts[k][1] = select(1, ...) or hosts[k][1]
278 hosts[k][2] = select(2, ...) or hosts[k][2]
279 hosts[k][3] = select(3, ...) or hosts[k][3]
280 hosts[k][4] = select(4, ...) or hosts[k][4]
284 if fs.access("/proc/net/arp") then
285 for e in io.lines("/proc/net/arp") do
286 ip, mac = e:match("^([%d%.]+)%s+%S+%s+%S+%s+([a-fA-F0-9:]+)%s+")
288 _add(what, mac:upper(), ip, nil, nil)
293 if fs.access("/etc/ethers") then
294 for e in io.lines("/etc/ethers") do
295 mac, ip = e:match("^([a-f0-9]%S+) (%S+)")
297 _add(what, mac:upper(), ip, nil, nil)
302 if fs.access("/var/dhcp.leases") then
303 for e in io.lines("/var/dhcp.leases") do
304 mac, ip, name = e:match("^%d+ (%S+) (%S+) (%S+)")
306 _add(what, mac:upper(), ip, nil, name ~= "*" and name)
311 cur:foreach("dhcp", "host",
313 for mac in luci.util.imatch(s.mac) do
314 _add(what, mac:upper(), s.ip, nil, s.name)
318 for _, e in ipairs(nixio.getifaddrs()) do
319 if e.name ~= "lo" then
320 ifn[e.name] = ifn[e.name] or { }
321 if e.family == "packet" and e.addr and #e.addr == 17 then
322 ifn[e.name][1] = e.addr:upper()
323 elseif e.family == "inet" then
324 ifn[e.name][2] = e.addr
325 elseif e.family == "inet6" then
326 ifn[e.name][3] = e.addr
331 for _, e in pairs(ifn) do
332 if e[what] and (e[2] or e[3]) then
333 _add(what, e[1], e[2], e[3], e[4])
337 for _, e in luci.util.kspairs(hosts) do
338 callback(e[1], e[2], e[3], e[4])
342 --- Returns a two-dimensional table of mac address hints.
343 -- @return Table of table containing known hosts from various sources.
344 -- Each entry contains the values in the following order:
346 function net.mac_hints(callback)
348 _nethints(1, function(mac, v4, v6, name)
349 name = name or nixio.getnameinfo(v4 or v6, nil, 100) or v4
350 if name and name ~= mac then
351 callback(mac, name or nixio.getnameinfo(v4 or v6, nil, 100) or v4)
356 _nethints(1, function(mac, v4, v6, name)
357 name = name or nixio.getnameinfo(v4 or v6, nil, 100) or v4
358 if name and name ~= mac then
359 rv[#rv+1] = { mac, name or nixio.getnameinfo(v4 or v6, nil, 100) or v4 }
366 --- Returns a two-dimensional table of IPv4 address hints.
367 -- @return Table of table containing known hosts from various sources.
368 -- Each entry contains the values in the following order:
370 function net.ipv4_hints(callback)
372 _nethints(2, function(mac, v4, v6, name)
373 name = name or nixio.getnameinfo(v4, nil, 100) or mac
374 if name and name ~= v4 then
380 _nethints(2, function(mac, v4, v6, name)
381 name = name or nixio.getnameinfo(v4, nil, 100) or mac
382 if name and name ~= v4 then
383 rv[#rv+1] = { v4, name }
390 --- Returns a two-dimensional table of IPv6 address hints.
391 -- @return Table of table containing known hosts from various sources.
392 -- Each entry contains the values in the following order:
394 function net.ipv6_hints(callback)
396 _nethints(3, function(mac, v4, v6, name)
397 name = name or nixio.getnameinfo(v6, nil, 100) or mac
398 if name and name ~= v6 then
404 _nethints(3, function(mac, v4, v6, name)
405 name = name or nixio.getnameinfo(v6, nil, 100) or mac
406 if name and name ~= v6 then
407 rv[#rv+1] = { v6, name }
414 --- Returns conntrack information
415 -- @return Table with the currently tracked IP connections
416 function net.conntrack(callback)
418 if fs.access("/proc/net/nf_conntrack", "r") then
419 for line in io.lines("/proc/net/nf_conntrack") do
420 line = line:match "^(.-( [^ =]+=).-)%2"
421 local entry, flags = _parse_mixed_record(line, " +")
422 if flags[6] ~= "TIME_WAIT" then
423 entry.layer3 = flags[1]
424 entry.layer4 = flags[3]
432 connt[#connt+1] = entry
436 elseif fs.access("/proc/net/ip_conntrack", "r") then
437 for line in io.lines("/proc/net/ip_conntrack") do
438 line = line:match "^(.-( [^ =]+=).-)%2"
439 local entry, flags = _parse_mixed_record(line, " +")
440 if flags[4] ~= "TIME_WAIT" then
441 entry.layer3 = "ipv4"
442 entry.layer4 = flags[1]
450 connt[#connt+1] = entry
460 --- Determine the current IPv4 default route. If multiple default routes exist,
461 -- return the one with the lowest metric.
462 -- @return Table with the properties of the current default route.
463 -- The following fields are defined:
464 -- { "dest", "gateway", "metric", "refcount", "usecount", "irtt",
465 -- "flags", "device" }
466 function net.defaultroute()
469 net.routes(function(rt)
470 if rt.dest:prefix() == 0 and (not route or route.metric > rt.metric) then
478 --- Determine the current IPv6 default route. If multiple default routes exist,
479 -- return the one with the lowest metric.
480 -- @return Table with the properties of the current default route.
481 -- The following fields are defined:
482 -- { "source", "dest", "nexthop", "metric", "refcount", "usecount",
483 -- "flags", "device" }
484 function net.defaultroute6()
487 net.routes6(function(rt)
488 if rt.dest:prefix() == 0 and rt.device ~= "lo" and
489 (not route or route.metric > rt.metric)
496 local global_unicast = luci.ip.IPv6("2000::/3")
497 net.routes6(function(rt)
498 if rt.dest:equal(global_unicast) and
499 (not route or route.metric > rt.metric)
509 --- Determine the names of available network interfaces.
510 -- @return Table containing all current interface names
511 function net.devices()
513 for k, v in ipairs(nixio.getifaddrs()) do
514 if v.family == "packet" then
515 devs[#devs+1] = v.name
522 --- Return information about available network interfaces.
523 -- @return Table containing all current interface names and their information
524 function net.deviceinfo()
526 for k, v in ipairs(nixio.getifaddrs()) do
527 if v.family == "packet" then
552 -- Determine the MAC address belonging to the given IP address.
553 -- @param ip IPv4 address
554 -- @return String containing the MAC address or nil if it cannot be found
555 function net.ip4mac(ip)
557 net.arptable(function(e)
558 if e["IP address"] == ip then
559 mac = e["HW address"]
565 --- Returns the current kernel routing table entries.
566 -- @return Table of tables with properties of the corresponding routes.
567 -- The following fields are defined for route entry tables:
568 -- { "dest", "gateway", "metric", "refcount", "usecount", "irtt",
569 -- "flags", "device" }
570 function net.routes(callback)
573 for line in io.lines("/proc/net/route") do
575 local dev, dst_ip, gateway, flags, refcnt, usecnt, metric,
576 dst_mask, mtu, win, irtt = line:match(
577 "([^%s]+)\t([A-F0-9]+)\t([A-F0-9]+)\t([A-F0-9]+)\t" ..
578 "(%d+)\t(%d+)\t(%d+)\t([A-F0-9]+)\t(%d+)\t(%d+)\t(%d+)"
582 gateway = luci.ip.Hex( gateway, 32, luci.ip.FAMILY_INET4 )
583 dst_mask = luci.ip.Hex( dst_mask, 32, luci.ip.FAMILY_INET4 )
584 dst_ip = luci.ip.Hex(
585 dst_ip, dst_mask:prefix(dst_mask), luci.ip.FAMILY_INET4
591 metric = tonumber(metric),
592 refcount = tonumber(refcnt),
593 usecount = tonumber(usecnt),
595 window = tonumber(window),
596 irtt = tonumber(irtt),
597 flags = tonumber(flags, 16),
604 routes[#routes+1] = rt
612 --- Returns the current ipv6 kernel routing table entries.
613 -- @return Table of tables with properties of the corresponding routes.
614 -- The following fields are defined for route entry tables:
615 -- { "source", "dest", "nexthop", "metric", "refcount", "usecount",
616 -- "flags", "device" }
617 function net.routes6(callback)
618 if fs.access("/proc/net/ipv6_route", "r") then
621 for line in io.lines("/proc/net/ipv6_route") do
623 local dst_ip, dst_prefix, src_ip, src_prefix, nexthop,
624 metric, refcnt, usecnt, flags, dev = line:match(
625 "([a-f0-9]+) ([a-f0-9]+) " ..
626 "([a-f0-9]+) ([a-f0-9]+) " ..
627 "([a-f0-9]+) ([a-f0-9]+) " ..
628 "([a-f0-9]+) ([a-f0-9]+) " ..
629 "([a-f0-9]+) +([^%s]+)"
632 if dst_ip and dst_prefix and
633 src_ip and src_prefix and
634 nexthop and metric and
635 refcnt and usecnt and
638 src_ip = luci.ip.Hex(
639 src_ip, tonumber(src_prefix, 16), luci.ip.FAMILY_INET6, false
642 dst_ip = luci.ip.Hex(
643 dst_ip, tonumber(dst_prefix, 16), luci.ip.FAMILY_INET6, false
646 nexthop = luci.ip.Hex( nexthop, 128, luci.ip.FAMILY_INET6, false )
652 metric = tonumber(metric, 16),
653 refcount = tonumber(refcnt, 16),
654 usecount = tonumber(usecnt, 16),
655 flags = tonumber(flags, 16),
658 -- lua number is too small for storing the metric
659 -- add a metric_raw field with the original content
666 routes[#routes+1] = rt
675 --- Tests whether the given host responds to ping probes.
676 -- @param host String containing a hostname or IPv4 address
677 -- @return Number containing 0 on success and >= 1 on error
678 function net.pingtest(host)
679 return os.execute("ping -c1 '"..host:gsub("'", '').."' >/dev/null 2>&1")
683 --- LuCI system utilities / process related functions.
685 -- @name luci.sys.process
688 --- Get the current process id.
690 -- @name process.info
691 -- @return Number containing the current pid
692 function process.info(key)
693 local s = {uid = nixio.getuid(), gid = nixio.getgid()}
694 return not key and s or s[key]
697 --- Retrieve information about currently running processes.
698 -- @return Table containing process information
699 function process.list()
702 local ps = luci.util.execi("/bin/busybox top -bn1")
709 local pid, ppid, user, stat, vsz, mem, cpu, cmd = line:match(
710 "^ *(%d+) +(%d+) +(%S.-%S) +([RSDZTW][W ][<N ]) +(%d+) +(%d+%%) +(%d+%%) +(.+)"
713 local idx = tonumber(pid)
731 --- Set the gid of a process identified by given pid.
732 -- @param gid Number containing the Unix group id
733 -- @return Boolean indicating successful operation
734 -- @return String containing the error message if failed
735 -- @return Number containing the error code if failed
736 function process.setgroup(gid)
737 return nixio.setgid(gid)
740 --- Set the uid of a process identified by given pid.
741 -- @param uid Number containing the Unix user id
742 -- @return Boolean indicating successful operation
743 -- @return String containing the error message if failed
744 -- @return Number containing the error code if failed
745 function process.setuser(uid)
746 return nixio.setuid(uid)
749 --- Send a signal to a process identified by given pid.
751 -- @name process.signal
752 -- @param pid Number containing the process id
753 -- @param sig Signal to send (default: 15 [SIGTERM])
754 -- @return Boolean indicating successful operation
755 -- @return Number containing the error code if failed
756 process.signal = nixio.kill
759 --- LuCI system utilities / user related functions.
761 -- @name luci.sys.user
764 --- Retrieve user informations for given uid.
767 -- @param uid Number containing the Unix user id
768 -- @return Table containing the following fields:
769 -- { "uid", "gid", "name", "passwd", "dir", "shell", "gecos" }
770 user.getuser = nixio.getpw
772 --- Retrieve the current user password hash.
773 -- @param username String containing the username to retrieve the password for
774 -- @return String containing the hash or nil if no password is set.
775 -- @return Password database entry
776 function user.getpasswd(username)
777 local pwe = nixio.getsp and nixio.getsp(username) or nixio.getpw(username)
778 local pwh = pwe and (pwe.pwdp or pwe.passwd)
779 if not pwh or #pwh < 1 or pwh == "!" or pwh == "x" then
786 --- Test whether given string matches the password of a given system user.
787 -- @param username String containing the Unix user name
788 -- @param pass String containing the password to compare
789 -- @return Boolean indicating wheather the passwords are equal
790 function user.checkpasswd(username, pass)
791 local pwh, pwe = user.getpasswd(username)
793 return (pwh == nil or nixio.crypt(pass, pwh) == pwh)
798 --- Change the password of given user.
799 -- @param username String containing the Unix user name
800 -- @param password String containing the password to compare
801 -- @return Number containing 0 on success and >= 1 on error
802 function user.setpasswd(username, password)
804 password = password:gsub("'", [['"'"']])
808 username = username:gsub("'", [['"'"']])
812 "(echo '" .. password .. "'; sleep 1; echo '" .. password .. "') | " ..
813 "passwd '" .. username .. "' >/dev/null 2>&1"
818 --- LuCI system utilities / wifi related functions.
820 -- @name luci.sys.wifi
823 --- Get wireless information for given interface.
824 -- @param ifname String containing the interface name
825 -- @return A wrapped iwinfo object instance
826 function wifi.getiwinfo(ifname)
827 local stat, iwinfo = pcall(require, "iwinfo")
831 local u = uci.cursor_state()
832 local d, n = ifname:match("^(%w+)%.network(%d+)")
836 u:foreach("wireless", "wifi-iface",
838 if s.device == d then
841 ifname = s.ifname or s.device
846 elseif u:get("wireless", ifname) == "wifi-device" then
847 u:foreach("wireless", "wifi-iface",
849 if s.device == ifname and s.ifname then
856 local t = stat and iwinfo.type(ifname)
857 local x = t and iwinfo[t] or { }
858 return setmetatable({}, {
859 __index = function(t, k)
860 if k == "ifname" then
871 --- LuCI system utilities / init related functions.
873 -- @name luci.sys.init
875 init.dir = "/etc/init.d/"
877 --- Get the names of all installed init scripts
878 -- @return Table containing the names of all inistalled init scripts
879 function init.names()
881 for name in fs.glob(init.dir.."*") do
882 names[#names+1] = fs.basename(name)
887 --- Get the index of he given init script
888 -- @param name Name of the init script
889 -- @return Numeric index value
890 function init.index(name)
891 if fs.access(init.dir..name) then
892 return call("env -i sh -c 'source %s%s enabled; exit ${START:-255}' >/dev/null"
897 local function init_action(action, name)
898 if fs.access(init.dir..name) then
899 return call("env -i %s%s %s >/dev/null" %{ init.dir, name, action })
903 --- Test whether the given init script is enabled
904 -- @param name Name of the init script
905 -- @return Boolean indicating whether init is enabled
906 function init.enabled(name)
907 return (init_action("enabled", name) == 0)
910 --- Enable the given init script
911 -- @param name Name of the init script
912 -- @return Boolean indicating success
913 function init.enable(name)
914 return (init_action("enable", name) == 1)
917 --- Disable the given init script
918 -- @param name Name of the init script
919 -- @return Boolean indicating success
920 function init.disable(name)
921 return (init_action("disable", name) == 0)
924 --- Start the given init script
925 -- @param name Name of the init script
926 -- @return Boolean indicating success
927 function init.start(name)
928 return (init_action("start", name) == 0)
931 --- Stop the given init script
932 -- @param name Name of the init script
933 -- @return Boolean indicating success
934 function init.stop(name)
935 return (init_action("stop", name) == 0)
939 -- Internal functions
941 function _parse_mixed_record(cnt, delimiter)
942 delimiter = delimiter or " "
946 for i, l in pairs(luci.util.split(luci.util.trim(cnt), "\n")) do
947 for j, f in pairs(luci.util.split(luci.util.trim(l), delimiter, nil, true)) do
948 local k, x, v = f:match('([^%s][^:=]*) *([:=]*) *"*([^\n"]*)"*')
952 table.insert(flags, k)