docs.intersystems.com
InterSystems IRIS Data Platform 2019.2  /  InterSystems Cloud Manager Guide  /  Using ICM  /  Deploy and Manage Services

InterSystems: The power behind what matters   
Search:  


Service Management Commands
These commands let you interact with the services running in your deployed containers, including InterSystems IRIS.
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 compute 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 ACME-DM-TEST-0001
Executing command in container iris on ACME-DM-TEST-0001
...output in ./ICM-4780136574/ACME-DM-TEST/ACME-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 on the -options option, 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 ACME-AM-TEST-0004 -interactive
Executing command 'bash' in container iris on ACME-AM-TEST-0004...
[root@localhost /] $ whoami
root
[root@localhost /] $ hostname
iris-ACME-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.
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. For example:
$ icm session -interactive -machine ACME-AM-TEST-0003 -namespace %SYS

Node: iris-ACME-AM-TEST-0003, Instance: IRIS

Username: _SYSTEM
Password: ********
%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 ACME-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 on the -options option, 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 ACME-AM-TEST-0003...
Executing command in container iris on ACME-AM-TEST-0004...
Executing command in container iris on ACME-AM-TEST-0005...
...output in ./ICM-4780136574/ACME-DM-TEST/ACME-AM-TEST-0003/ssh.out
...output in ./ICM-4780136574/ACME-DM-TEST/ACME-AM-TEST-0004/ssh.out
...output in ./ICM-4780136574/ACME-DM-TEST/ACME-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 ACME-DM-TEST-0001
...output in ./ICM-4780136574/ACME-DM-TEST/ACME-DM-TEST-0001/docker.out

0
icm cp
The icm cp command copies a local file or directory on the specified node into the specified container. The command syntax is as follows:
icm cp -localPath local-path [-remotePath remote-path]
Both localPath and remotePath can be either files or directories. If both are directories, the contents of the local directory are recursively copied; if you want the directory itself to be copied, include it in remotePath.
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. You can use the -container option to copy to a container other than the default iris.
Note:
See also the icm scp command, which securely copies a file or directory from the local ICM container to the specified host OS.
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 ACME-DM-TEST-0001...
...output in ./ICM-4780136574/ACME-DM-TEST/ACME-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.
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.
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 ACME-DM-TEST-0002
Executing command 'status --no-stream' on ACME-DM-TEST-0002...
...output in ./ICM-4780136574/ACME-DM-TEST/ACME-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.


Send us comments on this page
View this book as PDF   |  Download all PDFs
Copyright © 1997-2019 InterSystems Corporation, Cambridge, MA
Content Date/Time: 2019-09-19 06:44:29