Service Management Commands
These commands let you interact with the services running in your deployed containers, including InterSystems IRIS.
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 type of node for which the command should be run — for example, icm exec -role AM runs the specified command on only the nodes in the deployment that are of type AM — and the -image option to specify 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.
A significant feature of ICM is the ability it provides to interact with the nodes of your deployment on several levels — with the node itself, with the container deployed on it, and with the running InterSystems IRIS instance inside the container. The icm ssh (described in Infrastructure Management Commands), which lets you run a command on the specified host nodes, can be grouped with the first two commands described in this section, icm exec (run a command in the specified containers) and icm session (open an interactive session for the InterSystems IRIS instance on a specified node) as a set of powerful tools for interacting with your ICM deployment. These multiple levels of interaction are shown in the following illustration.
Interactive ICM Commands
icm exec
The icm exec command runs an arbitrary command in the specified containers, for example
$ icm exec -command "df -k" -machine ANDY-DM-TEST-0001
Executing command in container iris on ANDY-DM-TEST-0001
...output in ./state/ANDY-DM-TEST/ANDY-DM-TEST-0001/docker.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
Because mixing output from multiple commands would be hard to interpret, when the command is executed on more than one node, the output is written to files and a list of output files provided.
Additional Docker options, such as --env, can be specified on the icm exec command line using the -options option; for more information, see Using ICM with Custom and Third-Party Containers.
Because executing long-running, blocking, or interactive commands within a container can cause ICM to time out waiting for the command to complete or for user input, the icm exec command can also be used in interactive mode. 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. A good example is running a shell in the container:
$ icm exec -command bash -machine ANDY-AM-TEST-0004 -interactive
Executing command 'bash' in container iris on ANDY-AM-TEST-0004...
[root@localhost /] $ whoami
root
[root@localhost /] $ hostname
iris-ANDY-AM-TEST-0004
[root@localhost /] $ exit
Another example of a command to execute interactively within a container is an InterSystems IRIS command that prompts for user input, for example iris stop: which asks whether to broadcast a message before shutting down the InterSystems IRIS instance.
The icm cp command, which copies a local file or directory on the specified node into the specified container, is useful with icm exec.
icm session
When used with the -interactive option, the icm session command opens an interactive session for the InterSystems IRIS instance on the node you specify. The -namespace option can be used to specify the namespace in which the session starts; the default is the ICM-created namespace (IRISCLUSTER by default). For example:
$ icm session -interactive -machine ANDY-AM-TEST-0003 -namespace %SYS
Node: iris-ANDY-AM-TEST-0003, Instance: IRIS
%SYS>
You can also use the -command option to provide a routine to be run in the InterSystems IRIS session, for example:
icm session -interactive -machine ANDY-AM-TEST-0003 -namespace %SYS -command ^MIRROR
Additional Docker options, such as --env, can be specified on the icm exec command line using the -options option; for more information, see Using ICM with Custom and Third-Party Containers.
Without the -interactive option, the icm session command runs the InterSystems IRIS ObjectScriptScript snippet specified by the -command option on the specified node or nodes. The -namespace option can be used to specify the namespace in which the snippet runs. Because mixing output from multiple commands would be hard to interpret, when the command is executed on more than one node, the output is written to files and a list of output files provided. For example:
$ icm session -command 'Write ##class(%File).Exists("test.txt")' -role AM
Executing command in container iris on ANDY-AM-TEST-0003...
Executing command in container iris on ANDY-AM-TEST-0004...
Executing command in container iris on ANDY-AM-TEST-0005...
...output in ./state/ANDY-AM-TEST/ANDY-AM-TEST-0003/ssh.out
...output in ./state/ANDY-AM-TEST/ANDY-AM-TEST-0004/ssh.out
...output in ./state/ANDY-AM-TEST/ANDY-AM-TEST-0005/ssh.out
When the specified -machine or -role options limit the command to a single node, output is also written to the console, for example
$ icm session -command 'Write ##class(%File).Exists("test.txt")' -role DM
Executing command in container iris on ANDY-DM-TEST-0001
...output in ./state/ANDY-DM-TEST/ANDY-DM-TEST-0001/docker.out
0
The icm sql command, which runs an arbitrary SQL command against the containerized InterSystems IRIS instance on the specified node (or all nodes), is similar to icm session.
icm cp
The icm cp command copies a file or directory from the local file system on the specified node(s) into the specified container, or (if -options --retrieve is included) from the container to the local file system.
By default, the container is the iris container, and the copy is executed on all nodes. You can specify a different container using the -container option, and you can use the -role or -machine option to specify the node(s) on which the copy is executed. For example, to execute the copy only on the data server in a distributed cache cluster, you would include -role DM; to copy into or out of a custom container you have deployed rather than the iris containers, you would include -container container-name.
The basic command syntax is as follows:
icm cp -localPath local-path [-remotePath remote-path] [-options --retrieve]
Including -options --retrieve copies from remote-path (the absolute path within the container) to local-path (the absolute path on the local file system); if it is omitted, the copy is from local-path to remote-path. Both localPath and remotePath can be either files or directories. If both are directories, the contents of the source directory are recursively copied; if you want the directory itself to be copied, include it in the target path. The remotePath argument is optional and if omitted defaults to /tmp; if remotePath is a directory, it must contain a trailing forward slash (/) or it will be assumed to be a file.
Note:
See also the icm scp command, which securely copies a file or directory from the local ICM container to the specified host OS.
For more information on the -options option, which lets you include Docker arguments on the ICM command line, see Using ICM with Custom and Third-Party Containers.
icm sql
The icm sql command runs an arbitrary SQL command against the containerized InterSystems IRIS instance on the specified node (or all nodes), for example:
$ icm sql -command "SELECT Name,SMSGateway FROM %SYS.PhoneProviders" -role DM
Executing command in container iris on ANDY-DM-TEST-0001...
...output in ./state/ANDY-DM-TEST/ANDY-DM-TEST-0001/jdbc.out
Name,SMSGateway
AT&T Wireless,txt.att.net
Alltel,message.alltel.com
Cellular One,mobile.celloneusa.com
Nextel,messaging.nextel.com
Sprint PCS,messaging.sprintpcs.com
T-Mobile,tmomail.net
Verizon,vtext.com
The -namespace option can be used to specify the namespace in which the SQL command runs; the default is the ICM-created namespace (IRISCLUSTER by default).
Because mixing output from multiple commands would be hard to interpret, when the command is executed on more than one node, the output is written to files and a list of output files provided.
The icm sql command can also be interactively on a single node, opening an InterSystems IRIS SQL Shell (see the “Using the SQL Shell InterfaceOpens in a new tab” chapter of Using InterSystems SQL ). 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. For example:
$ icm sql -interactive -machine ANDY-QS-TEST-0002
SQL Command Line Shell
----------------------------------------------------
The command prefix is currently set to: <<nothing>>.
Enter <command>, 'q' to quit, '?' for help.
As with the noninteractive command, you can use the -namespace option interactively to specify the namespace in which the SQL shell runs; the default is the ICM-created namespace (IRISCLUSTER by default).
You can use the -role option to direct a SQL call to an LB node (load balancer) if its target pool comprises InterSystems IRIS nodes (DATA, COMPUTE, DM, or AM), for example:
$ icm sql -role LB -command "SELECT * FROM TABLE1"
icm docker
The icm docker command runs a Docker command on the specified node (or all nodes), for example:
$ icm docker -command "status --no-stream" -machine ANDY-DM-TEST-0002
Executing command 'status --no-stream' on ANDY-DM-TEST-0002...
...output in ./state/ANDY-DM-TEST/ANDY-DM-TEST-0002/docker.out
CONTAINER CPU % MEM USAGE / LIMIT MEM % NET I/O BLOCK I/O PIDS
3e94c3b20340 0.01% 606.9MiB/7.389GiB 8.02% 5.6B/3.5kB 464.5MB/21.79MB 0
1952342e3b6b 0.10% 22.17MiB/7.389GiB 0.29% 0B/0B 13.72MB/0B 0
d3bb3f9a756c 0.10% 40.54MiB/7.389GiB 0.54% 0B/0B 38.43MB/0B 0
46b263cb3799 0.14% 56.61MiB/7.389GiB 0.75% 0B/0B 19.32MB/231.9kB 0
The Docker command should not be long-running (or block), otherwise control will not return to ICM. For example, if the ---no-stream option in the example is removed, the call will not return until a timeout has expired.
