diff options
Diffstat (limited to 'pkgs/yossh/README.md')
| -rw-r--r-- | pkgs/yossh/README.md | 129 |
1 files changed, 129 insertions, 0 deletions
diff --git a/pkgs/yossh/README.md b/pkgs/yossh/README.md new file mode 100644 index 0000000..56179ae --- /dev/null +++ b/pkgs/yossh/README.md @@ -0,0 +1,129 @@ +# Yo SSH Host Initiator (Y.O.S.H.I) +Yoshi is a lua library that wraps the `ssh` client, allowing you to define complex host configurations using the power of a full programming langage (lua) instead of the `ssh_config` dsl. + +Obligatory code example (`~/bin/yossh`): +```lua +#!/usr/bin/env lua +yoshi = require'yoshi' + +local function isHome() + local _, _, code = os.execute("nc -z -w1 192.168.50.2 2222") + return code == 0 +end + +yoshi.hosts["ganymede"] = function() + if isHome() then + return yoshi.ssh{ + HostName = "192.168.50.2", + Port = 2222, + LocalForward = 8010 + } + else + return yoshi.ssh{ + HostName = "williamsfam.us.com", + LocalForward = 8010, + DynamicFoward = 9090 + } + end +end + +yoshi.hosts["io"] = function() + if isHome() then + return yoshi.ssh{HostName = "192.168.50.3"} + else + return yoshi.ssh{ + HostName = "192.168.50.3", + User = "admin", + ProxyJump = "collin@ganymede", + } + end +end + +yoshi.run(arg) +``` + +``` +$ yossh io +Connection to 192.168.50.2 2222 port [tcp/ethernet-ip-1] succeeded! ++ ssh admin@192.168.50.3 +io:~$ +``` + +## 🍄 Getting Started +First, clone this repo, and make sure you have ssh and lua installed. +``` +sudo apt install ssh luajit5.4 # or whatever +git clone https://github.com/bluedragon1221/yoshi +``` + +Next, place `yoshi.lua` in a place that lua can find it. +Consult the [lua documentation](https://www.lua.org/pil/8.1.html) for help. + +Now you can write a simple configuration. +As an example, let's look at the equivelant of this `ssh_config` block: +``` +Host box + HostName 192.168.50.3 + User yoshi +``` + +Using Yoshi, it would look like this: +```lua +-- yoshi_cfg.lua +yoshi = require'yoshi' + +yoshi.hosts["box"] = yoshi.ssh{ + HostName = "192.168.50.3", + User = "yoshi" +} + +yoshi.run(arg) +``` + +> (To create more complicated configurations, read the [docs](./doc/lua_doc.md)) + +To test your Yoshi configuration, you can run `lua yoshi_cfg.lua`. +This would be annoying to type every time you need to access your remote server, though! +So we'll place the script in the `$PATH` (ex. `~/bin/yossh` or something), and use a shabang to tell the script to execute with lua: +```lua +#!/usr/bin/env lua +yoshi = require'yoshi' + +yoshi.hosts["box"] = yoshi.ssh{ + HostName = "192.168.50.3", + User = "yoshi" +} + +yoshi.run(arg) +``` + +Assuming `~/bin` is in the `$PATH` and you made `yossh` executable with `chmod +x`, running `yossh` in the terminal will give you a nice help page: +```bash +$ yossh +yossh - smart SSH wrapper + +USAGE: + yossh <host> + yossh <user@host> + yossh <host:port> + yossh <user@host:port> + +AVAILABLE HOSTS: + - box +``` + +And you can ssh into `box`: +```bash +$ yossh box ++ ssh yoshi@192.168.50.3 +io:~$ whoami +yoshi +``` + +## 📖 Docs +- [`doc/lua_doc.md`](doc/lua_doc.md) contains comprehensive docs for the Yoshi lua api +- [`doc/nix.md`](doc/nix.md) discusses packaging your Yoshi configuration with nix + +--- + +[](https://brainmade.org) |