modules/luci-base/luasrc/sys.luadoc

   1 ---[[
   2 LuCI Linux and POSIX system utilities.
   3 ]]
   4 module "luci.sys"
   5
   6 ---[[
   7 Execute a given shell command and return the error code
   8
   9 @class          function
  10 @name           call
  11 @param          ...             Command to call
  12 @return         Error code of the command
  13 ]]
  14
  15 ---[[
  16 Execute a given shell command and capture its standard output
  17
  18 @class          function
  19 @name           exec
  20 @param command  Command to call
  21 @return                 String containing the return the output of the command
  22 ]]
  23
  24 ---[[
  25 Retrieve information about currently mounted file systems.
  26
  27 @class function
  28 @name mounts
  29 @return         Table containing mount information
  30 ]]
  31
  32 ---[[
  33 Retrieve environment variables. If no variable is given then a table
  34
  35 containing the whole environment is returned otherwise this function returns
  36 the corresponding string value for the given name or nil if no such variable
  37 exists.
  38 @class          function
  39 @name           getenv
  40 @param var      Name of the environment variable to retrieve (optional)
  41 @return         String containing the value of the specified variable
  42 @return         Table containing all variables if no variable name is given
  43 ]]
  44
  45 ---[[
  46 Get or set the current hostname.
  47
  48 @class function
  49 @name hostname
  50 @param          String containing a new hostname to set (optional)
  51 @return         String containing the system hostname
  52 ]]
  53
  54 ---[[
  55 Returns the contents of a documented referred by an URL.
  56
  57 @class function
  58 @name httpget
  59 @param url       The URL to retrieve
  60 @param stream Return a stream instead of a buffer
  61 @param target Directly write to target file name
  62 @return         String containing the contents of given the URL
  63 ]]
  64
  65 ---[[
  66 Initiate a system reboot.
  67
  68 @class function
  69 @name reboot
  70 @return Return value of os.execute()
  71 ]]
  72
  73 ---[[
  74 Retrieves the output of the "logread" command.
  75
  76 @class function
  77 @name syslog
  78 @return String containing the current log buffer
  79 ]]
  80
  81 ---[[
  82 Retrieves the output of the "dmesg" command.
  83
  84 @class function
  85 @name dmesg
  86 @return String containing the current log buffer
  87 ]]
  88
  89 ---[[
  90 Generates a random id with specified length.
  91
  92 @class function
  93 @name uniqueid
  94 @param bytes    Number of bytes for the unique id
  95 @return         String containing hex encoded id
  96 ]]
  97
  98 ---[[
  99 Returns the current system uptime stats.
 100
 101 @class function
 102 @name uptime
 103 @return String containing total uptime in seconds
 104 ]]
 105
 106 ---[[
 107 LuCI system utilities / network related functions.
 108
 109 @class  module
 110 @name   luci.sys.net
 111 ]]
 112
 113 ---[[
 114 Returns the current arp-table entries as two-dimensional table.
 115
 116 @class function
 117 @name net.arptable
 118 @return Table of table containing the current arp entries.
 119 --                      The following fields are defined for arp entry objects:
 120 --                      { "IP address", "HW address", "HW type", "Flags", "Mask", "Device" }
 121 ]]
 122
 123 ---[[
 124 Returns a two-dimensional table of mac address hints.
 125
 126 @class function
 127 @name net.mac_hints
 128 @return  Table of table containing known hosts from various sources.
 129          Each entry contains the values in the following order:
 130          [ "mac", "name" ]
 131 ]]
 132
 133 ---[[
 134 Returns a two-dimensional table of IPv4 address hints.
 135
 136 @class function
 137 @name net.ipv4_hints
 138 @return  Table of table containing known hosts from various sources.
 139          Each entry contains the values in the following order:
 140          [ "ip", "name" ]
 141 ]]
 142
 143 ---[[
 144 Returns a two-dimensional table of IPv6 address hints.
 145
 146 @class function
 147 @name net.ipv6_hints
 148 @return  Table of table containing known hosts from various sources.
 149          Each entry contains the values in the following order:
 150          [ "ip", "name" ]
 151 ]]
 152
 153 ---[[
 154 Returns a two-dimensional table of host hints.
 155
 156 @class function
 157 @name net.host_hints
 158 @return  Table of table containing known hosts from various sources,
 159          indexed by mac address. Each subtable contains at least one
 160          of the fields "name", "ipv4" or "ipv6".
 161 ]]
 162
 163 ---[[
 164 Returns conntrack information
 165
 166 @class function
 167 @name net.conntrack
 168 @return Table with the currently tracked IP connections
 169 ]]
 170
 171 ---[[
 172 Determine the names of available network interfaces.
 173
 174 @class function
 175 @name net.devices
 176 @return Table containing all current interface names
 177 ]]
 178
 179 ---[[
 180 Return information about available network interfaces.
 181
 182 @class function
 183 @name net.deviceinfo
 184 @return Table containing all current interface names and their information
 185 ]]
 186
 187 ---[[
 188 Returns the current kernel routing table entries.
 189
 190 @class function
 191 @name net.routes
 192 @return Table of tables with properties of the corresponding routes.
 193 --                      The following fields are defined for route entry tables:
 194 --                      { "dest", "gateway", "metric", "refcount", "usecount", "irtt",
 195 --                        "flags", "device" }
 196 ]]
 197
 198 ---[[
 199 Returns the current ipv6 kernel routing table entries.
 200
 201 @class function
 202 @name net.routes6
 203 @return Table of tables with properties of the corresponding routes.
 204 --                      The following fields are defined for route entry tables:
 205 --                      { "source", "dest", "nexthop", "metric", "refcount", "usecount",
 206 --                        "flags", "device" }
 207 ]]
 208
 209 ---[[
 210 Tests whether the given host responds to ping probes.
 211
 212 @class function
 213 @name net.pingtest
 214 @param host     String containing a hostname or IPv4 address
 215 @return         Number containing 0 on success and >= 1 on error
 216 ]]
 217
 218 ---[[
 219 LuCI system utilities / process related functions.
 220
 221 @class  module
 222 @name   luci.sys.process
 223 ]]
 224
 225 ---[[
 226 Get the current process id.
 227
 228 @class function
 229 @name  process.info
 230 @return Number containing the current pid
 231 ]]
 232
 233 ---[[
 234 Retrieve information about currently running processes.
 235
 236 @class function
 237 @name process.list
 238 @return         Table containing process information
 239 ]]
 240
 241 ---[[
 242 Set the gid of a process identified by given pid.
 243
 244 @class function
 245 @name process.setgroup
 246 @param gid      Number containing the Unix group id
 247 @return         Boolean indicating successful operation
 248 @return         String containing the error message if failed
 249 @return         Number containing the error code if failed
 250 ]]
 251
 252 ---[[
 253 Set the uid of a process identified by given pid.
 254
 255 @class function
 256 @name process.setuser
 257 @param uid      Number containing the Unix user id
 258 @return         Boolean indicating successful operation
 259 @return         String containing the error message if failed
 260 @return         Number containing the error code if failed
 261 ]]
 262
 263 ---[[
 264 Send a signal to a process identified by given pid.
 265
 266 @class function
 267 @name  process.signal
 268 @param pid      Number containing the process id
 269 @param sig      Signal to send (default: 15 [SIGTERM])
 270 @return         Boolean indicating successful operation
 271 @return         Number containing the error code if failed
 272 ]]
 273
 274 ---[[
 275 Execute a process, optionally capturing stdio.
 276
 277 Executes the process specified by the given argv vector, e.g.
 278 `{ "/bin/sh", "-c", "echo 1" }` and waits for it to terminate unless a true
 279 value has been passed for the "nowait" parameter.
 280
 281 When a function value is passed for the stdout or stderr arguments, the passed
 282 function is repeatedly called for each chunk read from the corresponding stdio
 283 stream. The read data is passed as string containing at most 4096 bytes at a
 284 time.
 285
 286 When a true, non-function value is passed for the stdout or stderr arguments,
 287 the data of the corresponding stdio stream is read into an internal string
 288 buffer and returned as "stdout" or "stderr" field respectively in the result
 289 table.
 290
 291 When a true value is passed to the nowait parameter, the function does not
 292 await process termination but returns as soon as all captured stdio streams
 293 have been closed or - if no streams are captured - immediately after launching
 294 the process.
 295
 296 @class function
 297 @name  process.exec
 298 @param commend  Table containing the argv vector to execute
 299 @param stdout   Callback function or boolean to indicate capturing (optional)
 300 @param stderr   Callback function or boolean to indicate capturing (optional)
 301 @param nowait   Don't wait for process termination when true (optional)
 302 @return         Table containing at least the fields "code" which holds the exit
 303             status of the invoked process or "-1" on error and "pid", which
 304             contains the process id assigned to the spawned process. When
 305             stdout and/or stderr capturing has been requested, it additionally
 306             contains "stdout" and "stderr" fields respectively, holding the
 307             captured stdio data as string.
 308 ]]
 309
 310 ---[[
 311 LuCI system utilities / user related functions.
 312
 313 @class  module
 314 @name   luci.sys.user
 315 ]]
 316
 317 ---[[
 318 Retrieve user information for given uid.
 319
 320 @class          function
 321 @name           getuser
 322 @param uid      Number containing the Unix user id
 323 @return         Table containing the following fields:
 324 --                              { "uid", "gid", "name", "passwd", "dir", "shell", "gecos" }
 325 ]]
 326
 327 ---[[
 328 Retrieve the current user password hash.
 329
 330 @class function
 331 @name user.getpasswd
 332 @param username String containing the username to retrieve the password for
 333 @return                 String containing the hash or nil if no password is set.
 334 @return                 Password database entry
 335 ]]
 336
 337 ---[[
 338 Test whether given string matches the password of a given system user.
 339
 340 @class function
 341 @name user.checkpasswd
 342 @param username String containing the Unix user name
 343 @param pass             String containing the password to compare
 344 @return                 Boolean indicating whether the passwords are equal
 345 ]]
 346
 347 ---[[
 348 Change the password of given user.
 349
 350 @class function
 351 @name user.setpasswd
 352 @param username String containing the Unix user name
 353 @param password String containing the password to compare
 354 @return                 Number containing 0 on success and >= 1 on error
 355 ]]
 356
 357 ---[[
 358 LuCI system utilities / wifi related functions.
 359
 360 @class  module
 361 @name   luci.sys.wifi
 362 ]]
 363
 364 ---[[
 365 Get wireless information for given interface.
 366
 367 @class function
 368 @name wifi.getiwinfo
 369 @param ifname        String containing the interface name
 370 @return              A wrapped iwinfo object instance
 371 ]]
 372
 373 ---[[
 374 LuCI system utilities / init related functions.
 375
 376 @class  module
 377 @name   luci.sys.init
 378 ]]
 379
 380 ---[[
 381 Get the names of all installed init scripts
 382
 383 @class function
 384 @name init.names
 385 @return Table containing the names of all inistalled init scripts
 386 ]]
 387
 388 ---[[
 389 Get the index of he given init script
 390
 391 @class function
 392 @name init.index
 393 @param name     Name of the init script
 394 @return         Numeric index value
 395 ]]
 396
 397 ---[[
 398 Test whether the given init script is enabled
 399
 400 @class function
 401 @name init.enabled
 402 @param name     Name of the init script
 403 @return         Boolean indicating whether init is enabled
 404 ]]
 405
 406 ---[[
 407 Enable the given init script
 408
 409 @class function
 410 @name init.enable
 411 @param name     Name of the init script
 412 @return         Boolean indicating success
 413 ]]
 414
 415 ---[[
 416 Disable the given init script
 417
 418 @class function
 419 @name init.disable
 420 @param name     Name of the init script
 421 @return         Boolean indicating success
 422 ]]
 423
 424 ---[[
 425 Start the given init script
 426
 427 @class function
 428 @name init.start
 429 @param name     Name of the init script
 430 @return         Boolean indicating success
 431 ]]
 432
 433 ---[[
 434 Stop the given init script
 435
 436 @class function
 437 @name init.stop
 438 @param name     Name of the init script
 439 @return         Boolean indicating success
 440 ]]
 441