Kanrisuru

Command

Kanrisuru::Command class encapsulates the process of creating commands to run on a remote server. This class also handles the raw stdout and stderror responses sent from the server, as well as the exit status.

Public Class Methods

new

Instantiating a new instance of Kanrisuru::Command should start with the base command name:

command = Kanrisuru::Command.new("uptime")

Public Instance Methods

append_value

Appends a value to the raw command. Note: This will automatically add white space between the command and new field added.

Note: << and + are aliases to this method.

command = Kanrisuru::Command.new("hello")
command.raw_command
"hello"

command.append_value("world")
command.raw_command
"hello world"

command << "-w options"
command.raw_command
"hello world -w options"

command + "-n fields"
command.raw_command
"hello world -w options -n fields"

pipe

Adds a pipe character when adding an option to a command. Mostly syntax sugar for building commands with piped programs in linux.

Note: | is an alias to this method.

command = Kanrisuru::Command.new("ps aux")
command.pipe("grep root")
command.raw_command
"ps aux | grep root"

command | "sort" 
command.raw_command
"ps aux | grep root | sort"

append_arg

Appends an argument to the command. This evaluates if the acutal argument is present or not to add to the command.

command = Kanrisuru::Command.new("groupadd rails")
command.append_arg("-g", nil)
command.raw_command
"groupadd rails"

command.append_arg("-g", 2000)
command.raw_command
"groupadd rails -g 2000"

append_flag

Appends a flag to the command. Evalutes boolean expression as second argument to append or not to the command.

command = Kanrisuru::Command.new("wget")
command.append_flag("--quiet", true)
command.raw_command
"wget --quiet"

append_valid_exit_code

Append a valid exit code to evaluate if the command was run successfully. Most commands use an exist code of 0, so this shouldn’t need to be called often. But there’s a few programs that use non-zero statuses that are considered succesful.

command = Kanrisuru::Command.new("zypper")
command.append_valid_exit_code(Kanrisuru::Core::Zypper::EXIT_INF_UPDATE_NEEDED)

command.handle_status(100)
command.success?
true

success?

Returns true if the valid_exit_codes include the the @exist_status.

command = Kanrisuru::Command.new('whoami')
command.handle_status(0)
command.success?
true

failure?

Returns true if the valid_exit_code does not include the @exit_status

command = Kanrisuru::Command.new('whoami')
command.handle_status(1)
command.failure?
true

to_a

Returns an array of strings split on \n characters.

command = Kanrisuru::Command.new('whoami')
command.handle_data("hello\n world")
command.to_a
[
  "hello",
  "world"
]

to_i

Attempts to cast result into an integer.

command = Kanrisuru::Command.new('whoami')
command.handle_data("124")
command.to_i
124

to_s

Casts entire return result as a single string, with splitting on the \n character.

command = Kanrisuru::Command.new('whoami')
command.handle_data("hello\n world")
command.to_s
"hello world"

to_json

Attempts to parse stringified version of result. Useful when a command has a JSON output mode.

command = Kanrisuru::Command.new('lsblk')
command.handle_data("{\n   \"blockdevices\": [\n      {\"name\":\"loop0\", \"fstype\":\"squashfs\", \"maj:min\":\"7:0\", \"mountpoint\":\"/snap/core18/2074\", \"size\":\"55.5M\", \"uuid\":null, \"ro\":true, \"rm\":false, \"owner\":\"root\", \"group\":\"disk\", \"mode\":\"brw-rw----\", \"type\":\"loop\"},\n      {\"name\":\"loop1\", \"fstype\":\"squashfs\", \"maj:min\":\"7:1\", \"mountpoint\":\"/snap/core18/2128\", \"size\":\"55.4M\", \"uuid\":null, \"ro\":true, \"rm\":false, \"owner\":\"root\", \"group\":\"disk\", \"mode\":\"brw-rw----\", \"type\":\"loop\"},\n      {\"name\":\"loop2\", \"fstype\":\"squashfs\", \"maj:min\":\"7:2\", \"mountpoint\":\"/snap/core20/1169\", \"size\":\"61.9M\", \"uuid\":null, \"ro\":true, \"rm\":false, \"owner\":\"root\", \"group\":\"disk\", \"mode\":\"brw-rw----\", \"type\":\"loop\"},\n      {\"name\":\"loop3\", \"fstype\":\"squashfs\", \"maj:min\":\"7:3\", \"mountpoint\":\"/snap/lxd/21029\", \"size\":\"70.3M\", \"uuid\":null, \"ro\":true, \"rm\":false, \"owner\":\"root\", \"group\":\"disk\", \"mode\":\"brw-rw----\", \"type\":\"loop\"},\n      {\"name\":\"loop4\", \"fstype\":\"squashfs\", \"maj:min\":\"7:4\", \"mountpoint\":\"/snap/core20/1081\", \"size\":\"61.8M\", \"uuid\":null, \"ro\":true, \"rm\":false, \"owner\":\"root\", \"group\":\"disk\", \"mode\":\"brw-rw----\", \"type\":\"loop\"},\n      {\"name\":\"loop6\", \"fstype\":\"squashfs\", \"maj:min\":\"7:6\", \"mountpoint\":\"/snap/snapd/13170\", \"size\":\"32.3M\", \"uuid\":null, \"ro\":true, \"rm\":false, \"owner\":\"root\", \"group\":\"disk\", \"mode\":\"brw-rw----\", \"type\":\"loop\"},\n      {\"name\":\"loop7\", \"fstype\":\"squashfs\", \"maj:min\":\"7:7\", \"mountpoint\":\"/snap/lxd/21545\", \"size\":\"67.3M\", \"uuid\":null, \"ro\":true, \"rm\":false, \"owner\":\"root\", \"group\":\"disk\", \"mode\":\"brw-rw----\", \"type\":\"loop\"},\n      {\"name\":\"loop8\", \"fstype\":\"squashfs\", \"maj:min\":\"7:8\", \"mountpoint\":\"/snap/snapd/13270\", \"size\":\"32.4M\", \"uuid\":null, \"ro\":true, \"rm\":false, \"owner\":\"root\", \"group\":\"disk\", \"mode\":\"brw-rw----\", \"type\":\"loop\"},\n      {\"name\":\"vda\", \"fstype\":null, \"maj:min\":\"252:0\", \"mountpoint\":null, \"size\":\"8G\", \"uuid\":null, \"ro\":false, \"rm\":false, \"owner\":\"root\", \"group\":\"disk\", \"mode\":\"brw-rw----\", \"type\":\"disk\",\n         \"children\": [\n            {\"name\":\"vda1\", \"fstype\":\"ext4\", \"maj:min\":\"252:1\", \"mountpoint\":\"/\", \"size\":\"7.9G\", \"uuid\":\"b8976b0d-6f88-49b9-8e4a-787323d98d2c\", \"ro\":false, \"rm\":false, \"owner\":\"root\", \"group\":\"disk\", \"mode\":\"brw-rw----\", \"type\":\"part\"},\n            {\"name\":\"vda14\", \"fstype\":null, \"maj:min\":\"252:14\", \"mountpoint\":null, \"size\":\"4M\", \"uuid\":null, \"ro\":false, \"rm\":false, \"owner\":\"root\", \"group\":\"disk\", \"mode\":\"brw-rw----\", \"type\":\"part\"},\n            {\"name\":\"vda15\", \"fstype\":\"vfat\", \"maj:min\":\"252:15\", \"mountpoint\":\"/boot/efi\", \"size\":\"106M\", \"uuid\":\"26F2-56F9\", \"ro\":false, \"rm\":false, \"owner\":\"root\", \"group\":\"disk\", \"mode\":\"brw-rw----\", \"type\":\"part\"}\n         ]\n      }\n   ]\n}\n")
command.to_json
{
  "blockdevices" => [
    {
            "name" => "loop0",
          "fstype" => "squashfs",
         "maj:min" => "7:0",
      "mountpoint" => "/snap/core18/2074" .. "owner" => "root",
           "group" => "disk",
            "mode" => "brw-rw----",
            "type" => "loop"
    },
    {
            "name" => "loop1",
          "fstype" => "squashfs",
         "maj:min" => "7:1",
      "mountpoint" => "/snap/core18/2128" .. "owner" => "root",
           "group" => "disk",
            "mode" => "brw-rw----",
            "type" => "loop"
    },
    {
            "name" => "loop2",
          "fstype" => "squashfs",
         "maj:min" => "7:2",
      "mountpoint" => "/snap/core20/1169" .. "owner" => "root",
           "group" => "disk",
            "mode" => "brw-rw----",
            "type" => "loop"
    }
  ]
}

prepared_command

Prepares command for running on a server. If a shell, user, environment variables were set, this will automatically add these.

command = Kanrisuru::Command.new("echo $VARIABLE")
command.prepared_command
"echo $VARIABLE"

command.remote_user = 'bob'
command.remote_shell = "/bin/bash"
command.remote_path = "/home/bob" 
command.remote_env = "export VARIABLE=hello;"
command.prepared_command
"export VARIABLE=hello; sudo -u bob /bin/bash -c \"cd /home/bob && echo $VARIABLE\""

raw_command

Returns the raw command that is used to track all the fields, args appended.

command = Kanrisuru::Command.new("tar --restrict")
command.raw_command
"tar --restrict"

command.append_arg('-C', '/home/ubuntu/dir')
command.append_arg('-f', '/home/ubuntu/dir/file1.txt')
command.append_flag('-c')
command.raw_command
"tar --restrict -C /home/ubuntu/dir -f /home/ubuntu/dir/file1.txt -c"

handle_data

Callback handler to append output data to the command. This is stored in a raw result array.

command = Kanrisuru::Command.new("cat /var/log/syslog")
command.handle_data("lots of logs")
command.handle_data("lots of logs")
command.handle_data("lots of logs")
command.raw_result
["lots of logs", "lots of logs", "lots of logs"]

handle_status

Callback handler to set the exit status of the program run.

command = Kanrisuru::Command.new("pwd")
command.handle_status(0)
command.exit_status
0

handle_signal

Callback handler to set the signal from the ssh session.

Per net-ssh docs: “if the remote process died as a result of a signal being sent to it, the signal will be reported as a string in the data, via data.read_string. (Not all SSH servers support this channel request type.)”