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 containg 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 containg 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 LuCI system utilities / user related functions.
 276
 277 @class  module
 278 @name   luci.sys.user
 279 ]]
 280
 281 ---[[
 282 Retrieve user informations for given uid.
 283
 284 @class          function
 285 @name           getuser
 286 @param uid      Number containing the Unix user id
 287 @return         Table containing the following fields:
 288 --                              { "uid", "gid", "name", "passwd", "dir", "shell", "gecos" }
 289 ]]
 290
 291 ---[[
 292 Retrieve the current user password hash.
 293
 294 @class function
 295 @name user.getpasswd
 296 @param username String containing the username to retrieve the password for
 297 @return                 String containing the hash or nil if no password is set.
 298 @return                 Password database entry
 299 ]]
 300
 301 ---[[
 302 Test whether given string matches the password of a given system user.
 303
 304 @class function
 305 @name user.checkpasswd
 306 @param username String containing the Unix user name
 307 @param pass             String containing the password to compare
 308 @return                 Boolean indicating wheather the passwords are equal
 309 ]]
 310
 311 ---[[
 312 Change the password of given user.
 313
 314 @class function
 315 @name user.setpasswd
 316 @param username String containing the Unix user name
 317 @param password String containing the password to compare
 318 @return                 Number containing 0 on success and >= 1 on error
 319 ]]
 320
 321 ---[[
 322 LuCI system utilities / wifi related functions.
 323
 324 @class  module
 325 @name   luci.sys.wifi
 326 ]]
 327
 328 ---[[
 329 Get wireless information for given interface.
 330
 331 @class function
 332 @name wifi.getiwinfo
 333 @param ifname        String containing the interface name
 334 @return              A wrapped iwinfo object instance
 335 ]]
 336
 337 ---[[
 338 LuCI system utilities / init related functions.
 339
 340 @class  module
 341 @name   luci.sys.init
 342 ]]
 343
 344 ---[[
 345 Get the names of all installed init scripts
 346
 347 @class function
 348 @name init.names
 349 @return Table containing the names of all inistalled init scripts
 350 ]]
 351
 352 ---[[
 353 Get the index of he given init script
 354
 355 @class function
 356 @name init.index
 357 @param name     Name of the init script
 358 @return         Numeric index value
 359 ]]
 360
 361 ---[[
 362 Test whether the given init script is enabled
 363
 364 @class function
 365 @name init.enabled
 366 @param name     Name of the init script
 367 @return         Boolean indicating whether init is enabled
 368 ]]
 369
 370 ---[[
 371 Enable the given init script
 372
 373 @class function
 374 @name init.enable
 375 @param name     Name of the init script
 376 @return         Boolean indicating success
 377 ]]
 378
 379 ---[[
 380 Disable the given init script
 381
 382 @class function
 383 @name init.disable
 384 @param name     Name of the init script
 385 @return         Boolean indicating success
 386 ]]
 387
 388 ---[[
 389 Start the given init script
 390
 391 @class function
 392 @name init.start
 393 @param name     Name of the init script
 394 @return         Boolean indicating success
 395 ]]
 396
 397 ---[[
 398 Stop the given init script
 399
 400 @class function
 401 @name init.stop
 402 @param name     Name of the init script
 403 @return         Boolean indicating success
 404 ]]
 405