knife ssh

The knife ssh subcommand is used to invoke SSH commands (in parallel) on a subset of nodes within an organization, based on the results of a search query made to the Chef server.

Syntax

This subcommand has the following syntax:

$ knife ssh SEARCH_QUERY SSH_COMMAND (options)

Options

Note

Review the list of common options available to this (and all) knife subcommands and plugins.

This subcommand has the following options:

-a SSH_ATTR, --attribute SSH_ATTR

The attribute that is used when opening the SSH connection. The default attribute is the FQDN of the host. Other possible values include a public IP address, a private IP address, or a hostname.

-A, --forward-agent

Use to enable SSH agent forwarding.

-C NUM, --concurrency NUM

The number of allowed concurrent connections.

-G GATEWAY, --ssh-gateway GATEWAY

The SSH tunnel or gateway that is used to run a bootstrap action on a machine that is not accessible from the workstation.

-i IDENTITY_FILE, --identity-file IDENTIFY_FILE

The SSH identity file used for authentication. Key-based authentication is recommended.

-m, --manual-list

Use to define a search query as a space-separated list of servers. If there is more than one item in the list, put quotes around the entire list. For example: --manual-list "server01 server 02 server 03"

--[no-]host-key-verify

Use --no-host-key-verify to disable host key verification. Default setting: --host-key-verify.

OTHER

The shell type. Possible values: interactive, screen, tmux, macterm, or cssh. (csshx is deprecated in favor of cssh.)

-p PORT, --ssh-port PORT

The SSH port.

-P PASSWORD, --ssh-password PASSWORD

The SSH password. This can be used to pass the password directly on the command line. If this option is not specified (and a password is required) knife will prompt for the password.

SEARCH_QUERY

The search query used to return a list of servers to be accessed using SSH and the specified SSH_COMMAND. This option uses the same syntax as the search sub-command.

SSH_COMMAND

The command that will be run against the results of a search query.

-x USER_NAME, --ssh-user USER_NAME

The SSH user name.

Examples

The following examples show how to use this knife subcommand:

Find server uptime

To find the uptime of all of web servers running Ubuntu on the Amazon EC2 platform, enter:

$ knife ssh "role:web" "uptime" -x ubuntu -a ec2.public_hostname

to return something like:

ec2-174-129-127-206.compute-1.amazonaws.com  13:50:47 up 1 day, 23:26,  1 user,  load average: 0.25, 0.18, 0.11
ec2-67-202-63-102.compute-1.amazonaws.com    13:50:47 up 1 day, 23:33,  1 user,  load average: 0.12, 0.13, 0.10
ec2-184-73-9-250.compute-1.amazonaws.com     13:50:48 up 16:45,  1 user,  load average: 0.30, 0.22, 0.13
ec2-75-101-240-230.compute-1.amazonaws.com   13:50:48 up 1 day, 22:59,  1 user,  load average: 0.24, 0.17, 0.11
ec2-184-73-60-141.compute-1.amazonaws.com    13:50:48 up 1 day, 23:30,  1 user,  load average: 0.32, 0.17, 0.15

Run the chef-client on all nodes

$ knife ssh 'name:*' 'sudo chef-client'

Force a chef-client run

To force a chef-client run on all of the web servers running Ubuntu on the Amazon EC2 platform, enter:

$ knife ssh "role:web" "sudo chef-client" -x ubuntu -a ec2.public_hostname

to return something like:

ec2-67-202-63-102.compute-1.amazonaws.com   [Fri, 22 Oct 2010 14:18:37 +0000] INFO: Starting Chef Run (Version 0.9.10)
ec2-174-129-127-206.compute-1.amazonaws.com [Fri, 22 Oct 2010 14:18:37 +0000] INFO: Starting Chef Run (Version 0.9.10)
ec2-184-73-9-250.compute-1.amazonaws.com    [Fri, 22 Oct 2010 14:18:38 +0000] INFO: Starting Chef Run (Version 0.9.10)
ec2-75-101-240-230.compute-1.amazonaws.com  [Fri, 22 Oct 2010 14:18:38 +0000] INFO: Starting Chef Run (Version 0.9.10)
ec2-184-73-60-141.compute-1.amazonaws.com   [Fri, 22 Oct 2010 14:18:38 +0000] INFO: Starting Chef Run (Version 0.9.10)
ec2-174-129-127-206.compute-1.amazonaws.com [Fri, 22 Oct 2010 14:18:39 +0000] INFO: Chef Run complete in 1.419243 seconds
ec2-174-129-127-206.compute-1.amazonaws.com [Fri, 22 Oct 2010 14:18:39 +0000] INFO: cleaning the checksum cache
ec2-174-129-127-206.compute-1.amazonaws.com [Fri, 22 Oct 2010 14:18:39 +0000] INFO: Running report handlers
ec2-174-129-127-206.compute-1.amazonaws.com [Fri, 22 Oct 2010 14:18:39 +0000] INFO: Report handlers complete
ec2-67-202-63-102.compute-1.amazonaws.com   [Fri, 22 Oct 2010 14:18:39 +0000] INFO: Chef Run complete in 1.578265 seconds
ec2-67-202-63-102.compute-1.amazonaws.com   [Fri, 22 Oct 2010 14:18:39 +0000] INFO: cleaning the checksum cache
ec2-67-202-63-102.compute-1.amazonaws.com   [Fri, 22 Oct 2010 14:18:39 +0000] INFO: Running report handlers
ec2-67-202-63-102.compute-1.amazonaws.com   [Fri, 22 Oct 2010 14:18:39 +0000] INFO: Report handlers complete
ec2-184-73-9-250.compute-1.amazonaws.com    [Fri, 22 Oct 2010 14:18:40 +0000] INFO: Chef Run complete in 1.638884 seconds
ec2-184-73-9-250.compute-1.amazonaws.com    [Fri, 22 Oct 2010 14:18:40 +0000] INFO: cleaning the checksum cache
ec2-184-73-9-250.compute-1.amazonaws.com    [Fri, 22 Oct 2010 14:18:40 +0000] INFO: Running report handlers
ec2-184-73-9-250.compute-1.amazonaws.com    [Fri, 22 Oct 2010 14:18:40 +0000] INFO: Report handlers complete
ec2-75-101-240-230.compute-1.amazonaws.com  [Fri, 22 Oct 2010 14:18:40 +0000] INFO: Chef Run complete in 1.540257 seconds
ec2-75-101-240-230.compute-1.amazonaws.com  [Fri, 22 Oct 2010 14:18:40 +0000] INFO: cleaning the checksum cache
ec2-75-101-240-230.compute-1.amazonaws.com  [Fri, 22 Oct 2010 14:18:40 +0000] INFO: Running report handlers
ec2-75-101-240-230.compute-1.amazonaws.com  [Fri, 22 Oct 2010 14:18:40 +0000] INFO: Report handlers complete
ec2-184-73-60-141.compute-1.amazonaws.com   [Fri, 22 Oct 2010 14:18:40 +0000] INFO: Chef Run complete in 1.502489 seconds
ec2-184-73-60-141.compute-1.amazonaws.com   [Fri, 22 Oct 2010 14:18:40 +0000] INFO: cleaning the checksum cache
ec2-184-73-60-141.compute-1.amazonaws.com   [Fri, 22 Oct 2010 14:18:40 +0000] INFO: Running report handlers
ec2-184-73-60-141.compute-1.amazonaws.com   [Fri, 22 Oct 2010 14:18:40 +0000] INFO: Report handlers complete

Run a command based on search query

To query for all nodes that have the webserver role and then use SSH to run the command sudo chef-client, enter:

$ knife ssh "role:webserver" "sudo chef-client"

Upgrade all nodes

$ knife ssh name:* "sudo aptitude upgrade -y"

Specify the shell type

To specify the shell type used on the nodes returned by a search query:

$ knife ssh roles:opscode-omnitruck macterm

where screen is one of the following values: cssh, interactive, macterm, screen, or tmux. If the node does not have the shell type installed, knife will return an error similar to the following:

you need the rb-appscript gem to use knife ssh macterm.
`(sudo) gem    install rb-appscript` to install
ERROR: LoadError: cannot load such file -- appscript