This is the development version of Kanrisuru. Since this is still a pre-1.0 release, we don't recommend using this in system-critical production environments.

Kanrisuru

Parsing Command Output

When running a command on a remote host with Kanrisuru, the results are returned in a predictable and well formated fashion.

Kanrisuru Result Class

Every result is returned in a Kanrisuru::Result class. This encapsulates the raw data from the command, exit status and with commands that return data, parsed and formatted structs with readable fields.

As an example, when running a simple command such as whoami:

require 'kanrisuru'

host = Kanrisuru::Remote::Host.new(host: 'localhost', username: 'ubuntu', keys: ['~/.ssh/id_rsa'])

result = host.whoami
result.success?
true

result.status
0

result.user
'ubuntu'


Standard across the result class is success?, failure?, status, data, and command. The first three methods are used to detect if the command ran succesfully or not on the remote host.

Note: Most commands consider an exist status of 0 to be succesful, and anything that's non-zero, to be considered a failed exit status. Some commands have exceptions to this; you can find what the success and failure exit statuses are for each command in the Kanrisuru docs, as well as their codes and an explanation of what these mean.

Kanrisuru Command Class

When a command is run with Kanrisuru, it’s first instantiated with the Kanrisuru::Command class. This encapsulates the underlying Linux command run on the remote machine, the raw data printed to stdout, as well as raw exit status returned from the host.

For the whoami command, the underlying command instance looks like:

result.command
#<Kanrisuru::Command:0x00005578c149d0d8 
  @valid_exit_codes=[0],
  @raw_command="whoami", 
  @raw_result=["ubuntu\n"], 
  @exit_status=0, 
  @remote_user="ubuntu", 
  @remote_shell="/bin/bash", 
  @remote_path="", 
  @remote_env=""
>


Even with this simple command and return result, there’s a few things going on under the hood with preparing and parsing data from the remote server.

With a more complex example, consider the ps command

result = host.ps(user: 0)

result.command
#<Kanrisuru::Command:0x00005578c15959b8 
  @valid_exit_codes=[0], 
  @raw_command="ps ww --user 0 -o uid,user,gid,group,ppid,pid,pcpu,pmem,stat,pri,flags,policy,time,cmd --no-headers", 
  @raw_result=["    0 root         0 root           0       1  0.0  0.5 Ss    19 4 TS  00:01:19 /sbin/init\n    0 root         0 root           0       2  0.0  0.0 S     19 1 TS  00:00:00 [kthreadd]\n    0 root         0 root           2       3  0.0  0.0 I<    39 1 TS  00:00:00 [rcu_gp]\n    0 root         0 root           2       4  0.0  0.0 I<    39 1 TS  00:00:00 [rcu_par_gp]\n    0 root         0 root           2       6  0.0  0.0 I<    39 1 TS  00:00:00 [kworker/0:0H-kblockd]\n    0 root         0 root           2       9  0.0  0.0 I<    39 1 TS  00:00:00 [mm_percpu_wq]\n    0 root         0 root           2      10  0.0  0.0 S     19 1 TS  00:00:01 [ksoftirqd/0]\n    0 root         0 root           2      11  0.0  0.0 I     19 1 TS  00:00:07 [rcu_sched]\n    0 root         0 root           2      12  0.0  0.0 S    139 1 FF  00:00:13 [migration/0]\n    0 root         0 root           2      13  0.0  0.0 S     90 5 FF  00:00:00 [idle_inject/0]\n    0 root         0 root           2      14  0.0  0.0 S     19 1 TS  00:00:00 [cpuhp/0]\n    0 root         0 root           2      15  0.0  0.0 S     19 5 TS  00:00:00 [kdevtmpfs]\n    0 root         0 root           2      16  0.0  0.0 I<    39 1 TS  00:00:00 [netns]\n    0 root         0 root           2      17  0.0  0.0 S     19 1 TS  00:00:00 [rcu_tasks_kthre]\n    0 root         0 root           2      18  0.0  0.0 S     19 1 TS  00:00:00 [kauditd]\n    0 root         0 root           2      19  0.0  0.0 S     19 1 TS  00:00:13 [khungtaskd]\n    0 root         0 root           2      20  0.0  0.0 S     19 1 TS  00:00:00 [oom_reaper]\n    0 root         0 root           2      21  0.0  0.0 I<    39 1 TS  00:00:00 [writeback]\n    0 root         0 root           2      22  0.0  0.0 S     19 1 TS  00:00:00 [kcompactd0]\n    0 root         0 root           2      23  0.0  0.0 SN    14 1 TS  00:00:00 [ksmd]\n    0 root         0 root           2      24  0.0  0.0 SN     0 1 TS  00:00:10 [khugepaged]\n    0 root         0 root           2      70  0.0  0.0 I<    39 1 TS  00:00:00 [kintegrityd]\n    0 root         0 root           2      71  0.0  0.0 I<    39 1 TS  00:00:00 [kblockd]\n    0 root         0 root           2      72  0.0  0.0 I<    39 1 TS  00:00:00 [blkcg_punt_bio]\n    0 root         0 root           2      73  0.0  0.0 I<    39 1 TS  00:00:00 [tpm_dev_wq]\n    0 root         0 root           2      74  0.0  0.0 I<    39 1 TS  00:00:00 [ata_sff]\n    0 root         0 root           2      75  0.0  0.0 I<    39 1 TS  00:00:00 [md]\n    0 root         0 root           2      76  0.0  0.0 I<    39 1 TS  00:00:00 [edac-poller]\n    0 root         0 root           2      77  0.0  0.0 I<    39 1 TS  00:00:00 [devfreq_wq]\n    0 root         0 root           2      78  0.0  0.0 S    139 1 FF  00:00:00 [watchdogd]\n    0 root         0 root           2      81  0.0  0.0 S     19 1 TS  00:00:00 [kswapd0]\n    0 root         0 root           2      82  0.0  0.0 S     19 1 TS  00:00:00 [ecryptfs-kthrea]\n    0 root         0 root           2      84  0.0  0.0 I<    39 1 TS  00:00:00 [kthrotld]\n    0 root         0 root           2      85  0.0  0.0 I<    39 1 TS  00:00:00 [acpi_thermal_pm]\n    0 root         0 root           2      86  0.0  0.0 S     19 1 TS  00:00:00 [scsi_eh_0]\n    0 root         0 root           2      87  0.0  0.0 I<    39 1 TS  00:00:00 [scsi_tmf_0]\n    0 root         0 root           2      88  0.0  0.0 S     19 1 TS  00:00:00 [scsi_eh_1]\n    0 root         0 root           2      89  0.0  0.0 I<    39 1 TS  00:00:00 [scsi_tmf_1]\n    0 root         0 root           2      91  0.0  0.0 I<    39 1 TS  00:00:00 [vfio-irqfd-clea]\n    0 root         0 root           2      93  0.0  0.0 I<    39 1 TS  00:00:00 [ipv6_addrconf]\n    0 root         0 root           2     102  0.0  0.0 I<    39 1 TS  00:00:00 [kstrp]\n    0 root         0 root           2     105  0.0  0.0 I<    39 1 TS  00:00:00 [kworker/u3:0-xprtiod]\n    0 root         0 root           2     118  0.0  0.0 I<    39 1 TS  00:00:00 [charger_manager]\n    0 root         0 root           2     158  0.0  0.0 I<    39 1 TS  00:00:00 [cryptd]\n  ", "  0 root         0 root           2     174  0.0  0.0 I<    39 1 TS  00:00:02 [kworker/0:1H-kblockd]\n    0 root         0 root           2     222  0.0  0.0 I<    39 1 TS  00:00:00 [raid5wq]\n    0 root         0 root           2     265  0.0  0.0 S     19 1 TS  00:00:03 [jbd2/vda1-8]\n    0 root         0 root           2     266  0.0  0.0 I<    39 1 TS  00:00:00 [ext4-rsv-conver]\n    0 root         0 root           2     302  0.0  0.0 S     19 1 TS  00:00:00 [hwrng]\n    0 root         0 root           1     350  0.0  0.9 S<s   20 4 TS  00:00:06 /lib/systemd/systemd-journald\n    0 root         0 root           2     353  0.0  0.0 I<    39 1 TS  00:00:00 [rpciod]\n    0 root         0 root           2     355  0.0  0.0 I<    39 1 TS  00:00:00 [xprtiod]\n    0 root         0 root           1     368  0.0  0.0 Ss    19 1 TS  00:00:00 /usr/sbin/blkmapd\n    0 root         0 root           1     379  0.0  0.2 Ss    19 4 TS  00:00:18 /lib/systemd/systemd-udevd\n    0 root         0 root           2     449  0.0  0.0 I<    39 1 TS  00:00:00 [kaluad]\n    0 root         0 root           2     450  0.0  0.0 I<    39 1 TS  00:00:00 [kmpath_rdacd]\n    0 root         0 root           2     451  0.0  0.0 I<    39 1 TS  00:00:00 [kmpathd]\n    0 root         0 root           2     452  0.0  0.0 I<    39 1 TS  00:00:00 [kmpath_handlerd]\n    0 root         0 root           1     453  0.0  0.8 SLsl 139 4 RR  00:02:39 /sbin/multipathd -d -s\n    0 root         0 root           2     464  0.0  0.0 S<    39 1 TS  00:00:00 [loop0]\n    0 root         0 root           2     465  0.0  0.0 S<    39 1 TS  00:00:00 [loop1]\n    0 root         0 root           2     469  0.0  0.0 S<    39 1 TS  00:00:00 [loop3]\n    0 root         0 root           2     473  0.0  0.0 S<    39 1 TS  00:00:00 [loop5]\n    0 root         0 root         0 root           2     564  0.0  0.0 I<    39 1 TS  00:00:00 [kworker/u3:1-xprtiod]\n    0 root         0 root           2     565  0.0  0.0 S     19 1 TS  00:00:00 [lockd]\n    0 root         0 root           2     570  0.0  0.0 S     19 1 TS  00:00:00 [nfsd]\n    0 root         0 root           2     571  0.0  0.0 S     19 1 TS  00:00:00 [nfsd]\n    0 root         0 root           2     572  0.0  0.0 S     19 1 TS  00:00:00 [nfsd]\n    0 root         0 root           2     573  0.0  0.0 S     19 1 TS  00:00:00 [nfsd]\n    0 root         0 root           2     574  0.0  0.0 S     19 1 TS  00:00:00 [nfsd]\n    0 root         0 root           2     575  0.0  0.0 S     19 1 TS  00:00:00 [nfsd]\n    0 root         0 root           2     576  0.0  0.0 S     19 1 TS  00:00:01 [nfsd]\n    0 root         0 root           2     577  0.0  0.0 S     19 1 TS  00:00:04 [nfsd]\n    0 root         0 root           1     610  0.0  0.4 Ssl   19 4 TS  00:01:01 /usr/lib/accountsservice/accounts-daemon\n    0 root         0 root           1     613  0.0  0.1 Ss    19 4 TS  00:00:15 /usr/sbin/cron -f\n    0 root         0 root           1     621  0.0  0.6 Ss    19 4 TS  00:00:00 /usr/bin/python3 /usr/bin/networkd-dispatcher --run-startup-triggers\n    0 root         0 root           1     636  0.0  0.3 Ss    19 4 TS  00:00:15 /lib/systemd/systemd-logind\n    0 root         0 root           1     642  0.0  0.1 Ss+   19 4 TS  00:00:00 /sbin/agetty -o -p -- \\u --keep-baud 115200,38400,9600 ttyS0 vt220\n    0 root         0 root           1     644  0.0  0.0 Ss+   19 4 TS  00:00:00 /sbin/agetty -o -p -- \\u --noclear tty1 linux\n    0 root         0 root           1     667  0.0  0.3 Ss    19 4 TS  00:00:00 sshd: /usr/sbin/sshd -D [listener] 0 of 10-100 startups\n    0 root         0 root           1     691  0.0  0.8 Ssl   19 4 TS  00:00:00 /usr/bin/python3 /usr/share/unattended-upgrades/unattended-upgrade-shutdown --wait-for-signal\n    0 root         0 root           1     704  0.0  0.3 Ssl   19 4 TS  00:00:00 /usr/lib/policykit-1/polkitd --no-debug\n    0 root         0 ro", "ot           2     970  0.0  0.0 S<    39 1 TS  00:00:00 [loop6]\n    0 root         0 root           1    1012  0.0  1.5 Ssl   19 4 TS  00:04:07 /usr/lib/snapd/snapd\n    0 root         0 root           2    1311  0.0  0.0 S<    39 1 TS  00:00:00 [loop4]\n    0 root         0 root           2    1411  0.0  0.0 S<    39 1 TS  00:00:00 [loop7]\n    0 root         0 root           2   16709  0.0  0.0 I<    39 1 TS  00:00:00 [xfsalloc]\n    0 root         0 root           2   16715  0.0  0.0 I<    39 1 TS  00:00:00 [xfs_mru_cache]\n    0 root         0 root           2   60839  0.0  0.0 S<    39 1 TS  00:00:00 [loop2]\n    0 root         0 root           2   64646  0.0  0.0 I     19 1 TS  00:00:00 [kworker/u2:2-events_unbound]\n    0 root         0 root           2   65983  0.0  0.0 I     19 1 TS  00:00:05 [kworker/0:1-events]\n    0 root         0 root         667   66973  0.0  0.4 Ss    19 4 TS  00:00:00 sshd: ubuntu [priv]\n    0 root         0 root           2   66985  0.0  0.0 I     19 1 TS  00:00:00 [kworker/0:0-cgroup_destroy]\n    0 root         0 root           2   67194  0.0  0.0 I     19 1 TS  00:00:00 [kworker/u2:0-events_power_efficient]\n    0 root         0 root         667   67198  0.0  0.4 Ss    19 4 TS  00:00:00 sshd: ubuntu [priv]\n"], 
  @exit_status=0
>


This is a pretty gnarly result. Luckily all commands run with Kanrisuru are parsed with the data extracted in a manner that’s easy for other applications to use.

Result Data

If data is returned from the remote host, Kanrisuru will parse this and provide it in the Kanrisuru::Result object.

For the whoami command, the data is returned as a custom struct instance, with the appropriate fields set on that instance.

result = host.whoami

result.data
#<Struct:Kanrisuru::Core::Path::UserName:0x00001810
  user = "ubuntu"
>

result.data.class
Kanrisuru::Core::Path::UserName


Kanrisuru also provides method mapping for struct fields tied to the result object. What this means is you can call direct getter methods on the underlying data object, eg

result.user
'ubuntu'


With data items that are mapped to an array of structs, like the ps example from earlier, the Kanrisuru::Result class also includes Enumerable for quick enumeration methods like each, map, and other filtering / selection methods.

result = host.ps(user: 'ubuntu')
result.to_a
[
  #<Struct:Kanrisuru::Core::System::ProcessInfo:0x00001888
    pid = 1,
    command = "/lib/systemd/systemd --user",
    cpu_time = "00:00:00",
    cpu_usage = 0.0,
    flags = 4,
    gid = 1000,
    group = "ubuntu",
    memory_usage = 0.4,
    pid = 66984,
    policy = "SCHED_OTHER",
    policy_abbr = "TS",
    priority = 19,
    stat = "Ss",
    uid = 1000,
    user = "ubuntu"
  >,
  #<Struct:Kanrisuru::Core::System::ProcessInfo:0x00001d10
    pid = 67088,
    command = "irb",
    cpu_time = "00:00:02",
    cpu_usage = 0.0,
    flags = 0,
    gid = 1000,
    group = "ubuntu",
    memory_usage = 2.2,
    pid = 67195,
    policy = "SCHED_OTHER",
    policy_abbr = "TS",
    priority = 19,
    stat = "S+",
    uid = 1000,
    user = "ubuntu"
  >,
  [2] .. [4],
  #<Struct:Kanrisuru::Core::System::ProcessInfo:0x00001e28
    pid = 67198,
    command = "sshd: ubuntu@notty",
    cpu_time = "00:00:00",
    cpu_usage = 0.0,
    flags = 5,
    gid = 1000,
    group = "ubuntu",
    memory_usage = 0.2,
    pid = 67281,
    policy = "SCHED_OTHER",
    policy_abbr = "TS",
    priority = 19,
    stat = "S",
    uid = 1000,
    user = "ubuntu"
  >,
  #<Struct:Kanrisuru::Core::System::ProcessInfo:0x00001f40
    pid = 67281,
    command = "ps ww --user ubuntu -o uid,user,gid,group,ppid,pid,pcpu,pmem,stat,pri,flags,policy,time,cmd --no-headers",
    cpu_time = "00:00:00",
    cpu_usage = 0.0,
    flags = 0,
    gid = 1000,
    group = "ubuntu",
    memory_usage = 0.1,
    pid = 67347,
    policy = "SCHED_OTHER",
    policy_abbr = "TS",
    priority = 19,
    stat = "Rs",
    uid = 1000,
    user = "ubuntu"
  >
]


As an example, to fetch the pids that are using the most memory on the system, run the ps command through the sort and map methods:

pids = host.ps.sort { |pa, pb| pb.memory_usage <=> pa.memory_usage }.map(&:pid)
pids[0..5]
[791, 67195, 1012, 561, 350, 453]


Checkout the core documentation for a more in-depth explanation on each command, their return fields and an description of what each field means.