modules/luci-base/luasrc/sys.luadoc

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