lua-eco

• Index

Contents

• Functions
• Class session

Modules

• eco
• eco.time
• eco.log
• eco.file
• eco.sys
• eco.sync
• eco.channel
• eco.shared
• eco.uci
• eco.ubus
• eco.socket
• eco.packet
• eco.dns
• eco.ssl
• eco.mqtt
• eco.net
• eco.nl
• eco.genl
• eco.rtnl
• eco.ip
• eco.nl80211
• eco.websocket
• eco.termios
• eco.ssh
• eco.http.server
• eco.http.client
• eco.encoding.hex
• eco.encoding.base64
• eco.hash.md5
• eco.hash.sha1
• eco.hash.sha256
• eco.hash.hmac

Topics

• README

Examples

• channel.lua
• coroutine.lua
• dns.lua
• base64.lua
• hex.lua
• env.lua
• exec.lua
• shell.lua
• dir.lua
• file.lua
• flock.lua
• inotify.lua
• walk.lua
• hmac.lua
• md5.lua
• sha1.lua
• sha256.lua
• hook.lua
• download_file.lua
• get.lua
• post.lua
• post_file.lua
• post_form.lua
• server.lua
• server_multiprocess.lua
• log.lua
• mqtt.lua
• custom-proto.lua
• genl_get_family.lua
• ip-addr-add.lua
• ip-addr-del.lua
• ip-addr-get.lua
• ip-link.lua
• link_del.lua
• link_dump.lua
• link_event.lua
• nl80211_add_interface.lua
• nl80211_del_interface.lua
• nl80211_dump_interface.lua
• nl80211_dump_station.lua
• nl80211_get_freqlist.lua
• nl80211_get_interface.lua
• nl80211_get_station.lua
• nl80211_scan.lua
• nl80211_set_interface.lua
• route_event.lua
• panic_hook.lua
• send-at-command.lua
• shared.lua
• signal.lua
• ping.lua
• ping6.lua
• recver.lua
• sender.lua
• arp-scan.lua
• arping.lua
• capture.lua
• send_tcp.lua
• send_udp.lua
• socketpair_dgram.lua
• socketpair_fork.lua
• socketpair_stream.lua
• client.lua
• server.lua
• client.lua
• server.lua
• client.lua
• dgram_client.lua
• dgram_server.lua
• server.lua
• spawn.lua
• exec.lua
• scp_recv.lua
• scp_send.lua
• client.lua
• server.lua
• cond.lua
• mutex.lua
• wait_group.lua
• termios.lua
• timer.lua
• signatures.lua
• subscribe.lua
• ubus.lua
• client.lua
• server.lua

Module eco.ssh

SSH support (libssh2).

This module provides a coroutine-friendly SSH client session with helpers for:

• executing a remote command
• SCP receive/send (string or file)

The underlying implementation uses non-blocking libssh2 calls. When libssh2 returns EAGAIN, the current coroutine yields until the socket becomes readable/writable.

Note: currently only password authentication is attempted (when the server advertises it). Other auth methods (public key, agent, keyboard- interactive) are not handled by this Lua wrapper.

Functions

new (ipaddr, port, username[, password])

Create a new SSH session.

Class session

session:exec (cmd[, timeout])	Execute a command on the remote host.
session:scp_recv (source[, dest])	Receive a remote file via SCP.
session:scp_send (data, dest)	Send data to the remote host via SCP.
session:scp_sendfile (source, dest)	Send a local file to the remote host via SCP.
session:disconnect ([reaason[, description]])	Disconnect the SSH session.
session:free ()	Close and free the session.

Functions

new (ipaddr, port, username[, password])

Create a new SSH session.

This call:

1. connects to the remote TCP endpoint
2. performs SSH handshake
3. attempts password authentication if the server advertises it

Parameters:

• ipaddr string Remote IP address (IPv4/IPv6).
• port int Remote port.
• username string Username.
• password string Password (used when password auth is supported). (optional)

Returns:

session Session object.

Or

1. nil On failure.
2. string Error message.

Class session

session:exec (cmd[, timeout])

Execute a command on the remote host.

The returned output is a concatenation of stdout and stderr.

Parameters:

• cmd string Command string.
• timeout number Timeout in seconds for reading output. (optional)

Returns:

1. string Command output (stdout+stderr).
2. int Exit status code.
3. string Exit signal name (or nil).

Or

1. nil On failure.
2. string Error message.

Usage:

local ssh = require 'eco.ssh'
local eco = require 'eco'

eco.run(function()
    local session<close>, err = ssh.new('127.0.0.1', 22, 'root', 'password')
    assert(session, err)

    local out, code, signal = session:exec('uptime')
    assert(out, code)
    print('exit:', code, 'signal:', signal)
    print(out)
end)

eco.loop()

session:scp_recv (source[, dest])

Receive a remote file via SCP.

If dest is provided, the remote file will be stored to that local path and this method returns the number of bytes written.

If dest is omitted, the whole file content is returned as a Lua string.

Parameters:

• source string Remote file path.
• dest string Local destination file path. (optional)

Returns:

any result When dest is not provided: file content (string). When dest is provided: bytes written (int).

Or

1. nil On failure.
2. string Error message.

Usage:

local ssh = require 'eco.ssh'
local eco = require 'eco'

eco.run(function()
    local session<close> = assert(ssh.new('127.0.0.1', 22, 'root', 'password'))
    local data = assert(session:scp_recv('/etc/os-release'))
    print(data)
    assert(session:scp_recv('/etc/os-release', '/tmp/os-release'))
end)

eco.loop()

session:scp_send (data, dest)

Send data to the remote host via SCP.

Creates/overwrites dest on the remote host.

Parameters:

• data string Content to send.
• dest string Remote destination file path.

Returns:

boolean true On success.

Or

1. nil On failure.
2. string Error message.

Usage:

local ok, err = session:scp_send('hello\n', '/tmp/hello')
assert(ok, err)

session:scp_sendfile (source, dest)

Send a local file to the remote host via SCP.

Parameters:

• source string Local file path.
• dest string Remote destination file path.

Returns:

boolean true On success.

Or

1. nil On failure.
2. string Error message.

session:disconnect ([reaason[, description]])

Disconnect the SSH session.

Parameters:

• reaason int Disconnect reason code (libssh2 constant). (optional)
• description string Disconnect description. (optional)

Returns:

boolean true On success.

Or

1. nil On failure.
2. string Error message.

session:free ()

Close and free the session.

This is also used as the __gc and __close metamethod.