1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
|
# Lua Documentation
Lua API documentation for Yoshi
## `yoshi.hosts`
- Description: List of defined ssh hosts. Each entry must be a function that returns an `sshCommand` when called.
- Type: table of `function(): sshCommand`
- Example:
```lua
yoshi.hosts["webserver"] = function()
-- this is just a random example to show why you might want yoshi.hosts[host] to be a function
if os.getenv("IM_FEELING") == "sad" then
return yoshi.ssh{HostName = "sad.webserver.local"}
else
return yoshi.ssh{HostName = "happy.webserver.local"}
end
end
```
## `yoshi.ssh`
- Description: Constructs an `sshCommand`
- Type: `function(table): sshCommand`
- Example:
```lua
yoshi.ssh{
HostName = "webserver.local",
Port = 2227,
ProxyJump = "bastion"
}
```
## `yoshi.sshCommand.User`
- Description: Specifies the target user in the ssh connection. Analogous to the `User` key in `ssh_config`
- Type: string or nil
- Example: `yoshi`, `collin123`
## `yoshi.sshCommand.HostName`
- Description: Specifies the target host in the ssh connection. The only required element to `yoshi.sshCommand`. Analogous to the `HostName` key in `ssh_config`
- Type: string
- Example: `192.168.0.27`, `github.com`, `140.82.114.3`
## `yoshi.sshCommand.Port`
- Description: Specifies the target port in the ssh connection. Defaults to `22` if unspecified. Analagous to the `Port` key in `ssh_config`
- Type: integer, `0 <= i <= 65535`
- Examples: `22`, `2222`, `2225`
## `yoshi.sshCommand.RemoteCommand`
- Description: Specifies a command to run on the target host instead of the default shell. Analagous to the `RemoteCommand` key in `ssh_config`
- Type: string
- Examples: `whoami`, `nixos-rebuild switch --flake /etc/nixos`, `tmux new-session -A`
## `yoshi.sshCommand.SessionType`
- Description: Specifies the type of ssh session. "none" means that no shell access is provded. Analogous to the `SessionType` key in `ssh_config`
- Type: "subsystem", "none", or "default"
- Examples: `"none"`
## `yoshi.sshCommand.LocalForward`
- Description: Specifies a port on the target host to forward to the local host in the format `{local_port, target_port}`. If no local port is specified, will assume host port and local port are the same. Analagous to the `LocalForward` key in `ssh_config` or the `-L` flag on the command line
- Type: `table[2] of integer` or integer, `0 <= i <= 65535`
- Examples: `8010`, `{8010, 80}`
## `yoshi.sshCommand.DynamicForward`
- Description: Specifies a port on the local host to serve as a SOCKS5 proxy, forwarding all traffic through the target host. Analagous to the `DynamicForward` key in `ssh_config` or the `-D` option on the command line
- Type: integer, `0 <= i <= 65535`
- Examples: `9090`
## `yoshi.sshCommand.ProxyJump`
- Description: Specifies a host to act as a gateway to the target host if not directly accessable by the local host. It will inherit `User`, `Port`, and `HostName` options from `yoshi.hosts[host]` if it exists. Analagous to the `ProxyJump` key in `ssh_config` or the `-J` flag on the command line
- Type: string in the form `user@host:port`
- Example: `box`, `yoshi@box`, `box:27`, `yoshi@box:27`
- Full Example:
```lua
yoshi.hosts["bastion"] = sshCommand.ssh{
HostName = "bastion.mywebsite.com",
Port = 23,
}
yoshi.hosts["server"] = sshCommand.ssh{
HostName = "192.168.0.2",
ProxyJump = "myuser@bastion"
}
assert_eq(
yoshi.getHost("server"):toCommand(),
"ssh -J myuser@bastion.mywebsite.com:23 server"
)
```
## `yoshi.sshCommand:toCommand`
- Description: Formats `self` as a valid `ssh` command to be run in the terminal.
- Type: `sshCommand:function(): string`
- Example:
```lua
os.execute(yoshi.getHost("io"):toCommand())
```
## `yoshi.getHost`
- Description: Looks up and evaluates `yoshi.hosts[hostname]`, returning the resulting `sshCommand`. Raises an error if the host is not found or the host function returns nil.
- Type: `function(string): sshCommand`
- Example:
```lua
yoshi.hosts["webserver"] = function()
return yoshi.ssh{
HostName = "webserver.local",
Port = 22,
ProxyJump = "bastion"
}
end
os.execute(yoshi.getHost("webserver"):toCommand())
```
## `yoshi.run`
- Description: Executes the ssh command associated with the given target host as provided by `arg`, a list of commandline arguments. If no arguments are provided, prints a help page. The first argument is a path of the form `[jumphost/.../]host`, where any leading path segments are used as explicit proxy jump hops. Subsequent arguments may include ssh flags such as `-D`, `-L`, `-N`, or `-- command`.
- Type: `function(table of string, table of any)`
- Example:
```lua
yoshi.run(arg, {dry_run = true}) -- arg is the global name for the lua program's commandline arguments
```
|
