Skip to content

Latest commit

 

History

History
86 lines (73 loc) · 4.07 KB

README.md

File metadata and controls

86 lines (73 loc) · 4.07 KB
Raw

iopshell

iopshell is a client written in Go, which allows the user to communicate with Inteno's IOPSYS devices, or other OpenWRT devices using the owsd server. Its primary goals are usability and to have a layer of abstraction handling all communications between the user and the device. iopshell is also capable of executing simple scripts, which can be used to automate certain tasks. iopshell is also capable of connecting locally, for example on the router itself.

Installation

Before installing iopshell, make sure you've installed Go >1.10 from here or using your distribution's package manager, and your $GOPATH and $GOBIN are properly set. You can then go get the dependencies and iopshell:

$ go get github.com/gorilla/websocket
$ go get github.com/chzyer/readline
$ go get github.com/nnsee/iopshell

In the future, prebuilt binaries will be provided.

Usage

Run a script:

$ $GOBIN/iopshell scripts/example.iop

Run the program as a shell:

$ $GOBIN/iopshell

You will be dropped to a shell prompt. Some example usage might look like this:

iop$ connect
iop$ auth admin admin
iop admin$ call uci get config:firewall

Note the custom paramater config:firewall. iopshell uses a custom parser for call params. This is to prevent having to write out json-formatted text. For example, take the following json:

{"key1": {"key1-1": "value1-1", "key1-2": "value1-2"}, "key2": "value2"}

In iopshell, this can be formatted as:

key1:key1-1:value1-1,key1-2:value1-2;key2:value2

which is a lot more painless to write out. Of course, if you prefer, you can still use fully JSON-formatted text - either works.

Additionally, there's an autocompleter to assist with the call command. After connecting, use the list command to enable tab-completion.

See the help command for further info.

Setting options

There are multiple options which can be seen and set with the set command. Using set with no arguments will simply print all editable options and their current values. Use set with arguments to change a value:

iop$ set verbose 1

Custom values will be lost after closing the program. To set permanent custom values, create a init.iop file in your iopshell config directory (Linux: $HOME/.config/iopshell/, Windows: C:\Users\%USER%\AppData\Roaming\iopshell\, MacOS: $HOME/Library/Application Support/iopshell/), and include commands to be run on launch. An example init.iop might look something like this:

set host 192.168.42.1
set user admin
set pass admin
connect
wait
auth

Reporting problems

If you encounter an issue, unintended behaviour or a crash, create a new issue. Don't forget to include:

  1. Steps to reproduce the issue
  2. Error log (if any)
  3. Host platform info: Operating system, CPU architecture

Writing custom commands

Implementing custom commands is easy. Save your custom command as commands/<command>.go. The file needs to be a part of the package commands and has to import internal/cmd. To get an idea of the structure of a command, take a look at auth.go. Don't forget to call .Register() in init(). Recompile and run.

Built with

License

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/>.