NAME¶
knife-ssh - The man page for the knife ssh subcommand.
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.
Syntax
This argument has the following syntax:
$ knife ssh SEARCH_QUERY SSH_COMMAND (options)
Options
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
- Indicates that SSH agent forwarding is enabled.
- -c CONFIG_FILE, --config CONFIG_FILE
- The configuration file to use.
- -C NUM, --concurrency NUM
- The number of allowed concurrent connections.
- --chef-zero-port PORT
- The port on which chef-zero will listen.
- --[no-]color
- Indicates whether colored output will be used.
- -d, --disable-editing
- Indicates that $EDITOR will not be opened; data will be accepted
as-is.
- --defaults
- Indicates that Knife will use the default value, instead of asking a user
to provide one.
- -e EDITOR, --editor EDITOR
- The $EDITOR that is used for all interactive commands.
- -E ENVIRONMENT, --environment ENVIRONMENT
- The name of the environment. When this option is added to a command, the
command will run only against the named environment.
- -F FORMAT, --format FORMAT
- The output format: summary (default), text, json,
yaml, and pp.
- -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.
- -h, --help
- Shows help for the command.
- -i IDENTITY_FILE, --identity-file IDENTIFY_FILE
- The SSH identity file used for authentication. Key-based authentication is
recommended.
- -k KEY, --key KEY
- The private key that Knife will use to sign requests made by the API
client to the server.
- -m, --manual-list
- Indicates that a search query is 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.
- --print-after
- Indicates that data will be shown after a destructive operation.
- -s URL, --server-url URL
- The URL for the server.
- 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.
- -u USER, --user USER
- The user name used by Knife to sign requests made by the API client to the
server. Authentication will fail if the user name does not match the
private key.
- -v, --version
- The version of the chef-client.
- -V, --verbose
- Set for more verbose outputs. Use -VV for maximum verbosity.
- -x USER_NAME, --ssh-user USER_NAME
- The SSH user name.
- -y, --yes
- Indicates that the response to all confirmation prompts will be
"Yes" (and that Knife will not ask for confirmation).
- -z, --local-mode
- Indicates that the chef-client will be run in local mode, which allows all
commands that work against the server to also work against the local
chef-repo.
Examples
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
$ knife ssh 'name:*' 'sudo chef-client'
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
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"
$ knife ssh name:* "sudo aptitude upgrade -y"
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
AUTHOR¶
Chef