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 conntrack information
 155
 156 @class function
 157 @name net.conntrack
 158 @return Table with the currently tracked IP connections
 159 ]]
 160
 161 ---[[
 162 Determine the names of available network interfaces.
 163
 164 @class function
 165 @name net.devices
 166 @return Table containing all current interface names
 167 ]]
 168
 169 ---[[
 170 Return information about available network interfaces.
 171
 172 @class function
 173 @name net.deviceinfo
 174 @return Table containing all current interface names and their information
 175 ]]
 176
 177 ---[[
 178 Returns the current kernel routing table entries.
 179
 180 @class function
 181 @name net.routes
 182 @return Table of tables with properties of the corresponding routes.
 183 --                      The following fields are defined for route entry tables:
 184 --                      { "dest", "gateway", "metric", "refcount", "usecount", "irtt",
 185 --                        "flags", "device" }
 186 ]]
 187
 188 ---[[
 189 Returns the current ipv6 kernel routing table entries.
 190
 191 @class function
 192 @name net.routes6
 193 @return Table of tables with properties of the corresponding routes.
 194 --                      The following fields are defined for route entry tables:
 195 --                      { "source", "dest", "nexthop", "metric", "refcount", "usecount",
 196 --                        "flags", "device" }
 197 ]]
 198
 199 ---[[
 200 Tests whether the given host responds to ping probes.
 201
 202 @class function
 203 @name net.pingtest
 204 @param host     String containing a hostname or IPv4 address
 205 @return         Number containing 0 on success and >= 1 on error
 206 ]]
 207
 208 ---[[
 209 LuCI system utilities / process related functions.
 210
 211 @class  module
 212 @name   luci.sys.process
 213 ]]
 214
 215 ---[[
 216 Get the current process id.
 217
 218 @class function
 219 @name  process.info
 220 @return Number containing the current pid
 221 ]]
 222
 223 ---[[
 224 Retrieve information about currently running processes.
 225
 226 @class function
 227 @name process.list
 228 @return         Table containing process information
 229 ]]
 230
 231 ---[[
 232 Set the gid of a process identified by given pid.
 233
 234 @class function
 235 @name process.setgroup
 236 @param gid      Number containing the Unix group id
 237 @return         Boolean indicating successful operation
 238 @return         String containing the error message if failed
 239 @return         Number containing the error code if failed
 240 ]]
 241
 242 ---[[
 243 Set the uid of a process identified by given pid.
 244
 245 @class function
 246 @name process.setuser
 247 @param uid      Number containing the Unix user id
 248 @return         Boolean indicating successful operation
 249 @return         String containing the error message if failed
 250 @return         Number containing the error code if failed
 251 ]]
 252
 253 ---[[
 254 Send a signal to a process identified by given pid.
 255
 256 @class function
 257 @name  process.signal
 258 @param pid      Number containing the process id
 259 @param sig      Signal to send (default: 15 [SIGTERM])
 260 @return         Boolean indicating successful operation
 261 @return         Number containing the error code if failed
 262 ]]
 263
 264 ---[[
 265 LuCI system utilities / user related functions.
 266
 267 @class  module
 268 @name   luci.sys.user
 269 ]]
 270
 271 ---[[
 272 Retrieve user informations for given uid.
 273
 274 @class          function
 275 @name           getuser
 276 @param uid      Number containing the Unix user id
 277 @return         Table containing the following fields:
 278 --                              { "uid", "gid", "name", "passwd", "dir", "shell", "gecos" }
 279 ]]
 280
 281 ---[[
 282 Retrieve the current user password hash.
 283
 284 @class function
 285 @name user.getpasswd
 286 @param username String containing the username to retrieve the password for
 287 @return                 String containing the hash or nil if no password is set.
 288 @return                 Password database entry
 289 ]]
 290
 291 ---[[
 292 Test whether given string matches the password of a given system user.
 293
 294 @class function
 295 @name user.checkpasswd
 296 @param username String containing the Unix user name
 297 @param pass             String containing the password to compare
 298 @return                 Boolean indicating wheather the passwords are equal
 299 ]]
 300
 301 ---[[
 302 Change the password of given user.
 303
 304 @class function
 305 @name user.setpasswd
 306 @param username String containing the Unix user name
 307 @param password String containing the password to compare
 308 @return                 Number containing 0 on success and >= 1 on error
 309 ]]
 310
 311 ---[[
 312 LuCI system utilities / wifi related functions.
 313
 314 @class  module
 315 @name   luci.sys.wifi
 316 ]]
 317
 318 ---[[
 319 Get wireless information for given interface.
 320
 321 @class function
 322 @name wifi.getiwinfo
 323 @param ifname        String containing the interface name
 324 @return              A wrapped iwinfo object instance
 325 ]]
 326
 327 ---[[
 328 LuCI system utilities / init related functions.
 329
 330 @class  module
 331 @name   luci.sys.init
 332 ]]
 333
 334 ---[[
 335 Get the names of all installed init scripts
 336
 337 @class function
 338 @name init.names
 339 @return Table containing the names of all inistalled init scripts
 340 ]]
 341
 342 ---[[
 343 Get the index of he given init script
 344
 345 @class function
 346 @name init.index
 347 @param name     Name of the init script
 348 @return         Numeric index value
 349 ]]
 350
 351 ---[[
 352 Test whether the given init script is enabled
 353
 354 @class function
 355 @name init.enabled
 356 @param name     Name of the init script
 357 @return         Boolean indicating whether init is enabled
 358 ]]
 359
 360 ---[[
 361 Enable the given init script
 362
 363 @class function
 364 @name init.enable
 365 @param name     Name of the init script
 366 @return         Boolean indicating success
 367 ]]
 368
 369 ---[[
 370 Disable the given init script
 371
 372 @class function
 373 @name init.disable
 374 @param name     Name of the init script
 375 @return         Boolean indicating success
 376 ]]
 377
 378 ---[[
 379 Start the given init script
 380
 381 @class function
 382 @name init.start
 383 @param name     Name of the init script
 384 @return         Boolean indicating success
 385 ]]
 386
 387 ---[[
 388 Stop the given init script
 389
 390 @class function
 391 @name init.stop
 392 @param name     Name of the init script
 393 @return         Boolean indicating success
 394 ]]
 395