Train - Transport Interface

Train lets you talk to your local or remote operating systems with a unified interface.

It allows you to:

execute commands via run_command
interact with files via file
identify the target operating system via os

Train supports:

Local execution
SSH
WinRM
Docker
Mock (for testing and debugging)

Examples

Setup

Local

require 'train'
train = Train.create('local')

SSH

require 'train'
train = Train.create('ssh',
  host: '1.2.3.4', port: 22, user: 'root', key_files: '/vagrant')

If you don't specify the key_files and password options, SSH agent authentication will be attempted. For example:

require 'train'
train = Train.create('ssh', host: '1.2.3.4', port: 22, user: 'root')

WinRM

require 'train'
train = Train.create('winrm',
  host: '1.2.3.4', user: 'Administrator', password: '...', ssl: true, self_signed: true)

Docker

require 'train'
train = Train.create('docker', host: 'container_id...')

Configuration

To get a list of available options for a plugin:

puts Train.options('ssh')

This will provide all configuration options:

{
  :host     => { :required => true},
  :port     => { :default  => 22, :required => true},
  :user     => { :default  => "root", :required => true},
  :keys     => { :default  => nil},
  :password => { :default  => nil},
  ...

Usage

# start or reuse a connection
conn = train.connection

# run a command on Linux/Unix/Mac
puts conn.run_command('whoami').stdout

# get OS info
puts conn.os[:family]
puts conn.os[:release]

# access files
puts conn.file('/proc/version').content

# close the connection
conn.close

Testing

We perform unit, integration and windows tests.

unit tests ensure the intended behaviour of the implementation
integration tests run against VMs and docker containers
windows tests that run on appveyor for windows integration tests

Mac/Linux

bundle exec ruby -W -Ilib:test/unit test/unit/extras/stat_test.rb

Windows

# run windows tests
bundle exec rake test:windows

# run single tests
bundle exec ruby -I .\test\windows\ .\test\windows\local_test.rb

Kudos and Contributors

Train is heavily based on the work of:

test-kitchen

by Fletcher Nichol and a great community of contributors
ohai

by Adam Jacob, Chef Software Inc. and a great community of contributors

We also want to thank halo who did a great contribution by handing over the train gem name.

Contributing

Fork it
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Create new Pull Request

License

| Author: | Dominik Richter (drichter@chef.io)

| Author: | Christoph Hartmann (chartmann@chef.io)

| License: | Apache License, Version 2.0

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Sharpie / train