Infrastructure Management Commands
The commands in this section are used to manage the infrastructure you have provisioned using ICM.
Many ICM command options can be used with more than one command. For example, the -role option can be used with a number of commands to specify the of the nodes for which the command should be run — for example, icm inventory -role AM lists only the nodes in the deployment that are of type AM — and the -image option, which specifies an image from which to deploy containers for both the icm run and icm upgrade commands. For complete lists of ICM commands and their options, see ICM Commands and Options in the “ICM Reference” chapter.
icm inventory
The icm inventory command lists the provisioned nodes, as at the end of the provisioning output, based on the information in the instances.json file (see The Instances File in the chapter “Essential ICM Elements”). For example:
$ icm inventory
Machine IP Address DNS Name Region Zone
------- ---------- -------- ------ ----
ANDY-DM-TEST-0001+ 00.53.183.209 ec2-00-53-183-209.us-west-1.compute.amazonaws.com us-west-1 c
ANDY-DM-TEST-0002- 00.53.183.185 ec2-00-53-183-185.us-west-1.compute.amazonaws.com us-west-1 c
ANDY-AM-TEST-0003 00.56.59.42 ec2-00-56-59-42.us-west-1.compute.amazonaws.com us-west-1 c
ANDY-AM-TEST-0005 00.67.1.11 ec2-00-67-1-11.us-west-1.compute.amazonaws.com us-west-1 c
ANDY-AM-TEST-0003 00.193.117.217 ec2-00-193-117-217.us-west-1.compute.amazonaws.com us-west-1 c
ANDY-LB-TEST-0002 (virtual AM) ANDY-AM-TEST-1546467861.amazonaws.com us-west-1 c
ANDY-AR-TEST-0006 00.53.201.194 ec2-00-53-201-194.us-west-1.compute.amazonaws.com us-west-1 c
Note:
When mirrored nodes are part of a configuration, initial mirror failover assignments are indicated by a + (plus) following the machine name of each intended primary and a - (minus) following the machine name of each intended backup, as shown in the preceding example. These assignments can change, however; following deployment, use the icm ps command to display the mirror member status of the deployed nodes.
You can also use the -machine or -role options to filter by node name or role, for example, with the same cluster as in the preceding example:
$ icm inventory -role AM
Machine IP Address DNS Name Region Zone
------- ---------- -------- ------ ----
ANDY-AM-TEST-0003 00.56.59.42 ec2-00-56-59-42.us-west-1.compute.amazonaws.com us-west-1 c
ANDY-AM-TEST-0005 00.67.1.11 ec2-00-67-1-11.us-west-1.compute.amazonaws.com us-west-1 c
ANDY-AM-TEST-0003 00.193.117.217 ec2-00-193-117-217.us-west-1.compute.amazonaws.com us-west-1 c
If the fully qualified DNS names from the cloud provider are too wide for a readable display, you can use the -options option with the Docker wide argument to make the output wider, for example:
icm inventory -options wide
For more information on the -options option, see Using ICM with Custom and Third-Party Containers.
icm ssh
The icm ssh command runs an arbitrary command on the specified host nodes. Because mixing output from multiple commands would be hard to interpret, the output is written to files and a list of output files provided, for example:
$ icm ssh -command "ping -c 5 intersystems.com" -role DM
Executing command 'ping -c 5 intersystems.com' on ANDY-DM-TEST-0001...
Executing command 'ping -c 5 intersystems.com' on ANDY-DM-TEST-0002...
...output in ./state/ANDY-DM-TEST/ANDY-DM-TEST-0001/ssh.out
...output in ./state/ANDY-DM-TEST/ANDY-DM-TEST-0002/ssh.out
However, when the -machine and/or -role options are used to specify exactly one node, as in the following, or there is only one node, the output is also written to the console:
$ icm ssh -command "df -k" -machine ANDY-DM-TEST-0001
Executing command 'df -k' on ANDY-DM-TEST-0001...
...output in ./state/ANDY-DM-TEST/ANDY-DM-TEST-0001/ssh.out
Filesystem 1K-blocks Used Available Use% Mounted on
rootfs 10474496 2205468 8269028 22% /
tmpfs 3874116 0 3874116 0% /dev
tmpfs 3874116 0 3874116 0% /sys/fs/cgroup
/dev/xvda2 33542124 3766604 29775520 12% /host
/dev/xvdb 10190100 36888 9612540 1% /irissys/data
/dev/xvdc 10190100 36888 9612540 1% /irissys/wij
/dev/xvdd 10190100 36888 9612540 1% /irissys/journal1
/dev/xvde 10190100 36888 9612540 1% /irissys/journal2
shm 65536 492 65044 1% /dev/shm
The icm ssh command can also be used in interactive mode to execute long-running, blocking, or interactive commands on a host node. Unless the command is run on a single-node deployment, the -interactive flag must be accompanied by a -role or -machine option restricting the command to a single node. If the -command option is not used, the destination user's default shell (for example bash) is launched.
See icm exec for an example of running a command interactively.
Note:
Two commands described in Service Management Commands, icm exec (which runs an arbitrary command on the specified containers) and icm session (which opens an interactive session for the InterSystems IRIS instance on a specified node) can be grouped with icm ssh as a set of powerful tools for interacting with your ICM deployment. The icm scp command, which securely copies a file or directory from the local ICM container to the host OS of the specified node or nodes, is frequently used with icm ssh.
icm scp
The icm scp command securely copies a file or directory from the local ICM container to the local file system of the specified node or nodes. The command syntax is as follows:
icm scp -localPath local-path [-remotePath remote-path]
Both localPath and remotePath can be either files or directories. If remotePath is a directory, it must contain a trailing forward slash (/), or it will be assumed to be a file. If both are directories, the contents of the local directory are recursively copied; if you want the directory itself to be copied, remove the trailing slash (/) from localPath.
The user specified by the SSHUser field must have the needed permissions for the host file system location specified by the optional remote-path argument. The default for remote-path is $HOME as defined in the host OS.
Note:
See also the icm cp command, which copies a local file or directory on the specified node into the specified container, or from the container onto the local file system.
