README.md
1# Shell agent
2
3[](https://travis-ci.org/puppetlabs/mcollective-shell-agent)
4
5The shell agent allows you to start and manage shell commands via
6mcollective.
7
8It allows the running of long-running processes with a mechanism to check in
9on the output from these long-running processes, which is independent of the
10mcollective daemon process (the daemon can be restarted without interrupting
11the processes)
12
13To use this agent you need at least:
14
15* MCollective 2.2.4
16* Ruby 1.9 (for Process#spawn)
17
18Please report any errors or make feature requests in the [MCOP jira project][MCOP]
19
20Please note: we do not recommend this agent as a way of building out your
21automation, for that you're still better off writing your own tailored
22[agents][writing-agents] that fit your use case. This agent is targeted
23at the ad-hoc needs that people ocassionaly have.
24
25[writing-agents]: http://docs.puppetlabs.com/mcollective/simplerpc/agents.html
26[MCOP]: http://tickets.puppetlabs.com/browse/MCOP
27
28## Installation
29
30Follow the [basic plugin install guide][install guide], taking all
31the code from lib and adding it to your MCollective $libdir
32
33[install guide]: http://projects.puppetlabs.com/projects/mcollective-plugins/wiki/InstalingPlugins
34
35
36## Configuring the agent
37
38The agent should work without any additional configuration, though there are
39some options you can tune the mcollective server.cfg.
40
41### `plugin.shell.state_directory`
42
43This is where the state used to track processes will live. By default this
44will be /var/run/mcollective-shell on Unix systems.
45
46```
47plugin.shell.state_directory = /opt/run/mcollective-shell
48```
49
50
51## Application usage
52
53The `mco shell` application has several subcommands to start and manage
54processes.
55
56### mco shell run
57
58Runs a command and reports back. Use this for discrete short-living commands.
59
60For long-running commands look at `start` or `run --tail`.
61
62```
63$ mco shell run dir
64
65 * [ ============================================================> ] 2 / 2
66
67master:
68bin dev home lib64 media opt root selinux srv tmp vagrant
69boot etc lib lost+found mnt proc sbin src sys usr var
70
71server2008r2a:
72 Volume in drive C has no label.
73 Volume Serial Number is DADF-75F9
74
75 Directory of C:\
76
7709/22/2012 11:45 AM <SYMLINKD> manifests [\\vboxsrv\manifests]
7809/22/2012 11:45 AM <SYMLINKD> modules [\\vboxsrv\modules]
7907/13/2009 08:20 PM <DIR> PerfLogs
8009/22/2012 11:42 AM <DIR> Program Files
8103/27/2014 06:52 AM <DIR> Program Files (x86)
8207/03/2014 07:42 AM <SYMLINKD> src [\\vboxsrv\C:_src]
8303/27/2014 06:39 AM <DIR> Users
8407/03/2014 07:42 AM <SYMLINKD> vagrant [\\vboxsrv\vagrant]
8503/27/2014 06:41 AM <DIR> Windows
86 0 File(s) 0 bytes
87 9 Dir(s) 34,565,091,328 bytes free
88
89
90Finished processing 2 / 2 hosts in 221.28 ms
91```
92
93### mco shell run --tail
94
95Starts a command, shows you the output from it, kills the command when you
96interrupt with control-c, exits normally when the command exits.
97
98```
99$ mco shell -I /master/ run --tail vmstat 1
100
101 * [ ============================================================> ] 1 / 1
102
103master stdout: procs -----------memory---------- ---swap-- -----io---- --system-- -----cpu-----
104master stdout: r b swpd free buff cache si so bi bo in cs us sy id wa st
105master stdout: 0 1 445812 120584 5808 37348 34 29 52 48 39 47 6 1 93 0 0
106master stdout: 1 0 445112 122692 5824 37332 2692 0 2692 84 911 2089 47 9 40 4 0
107master stdout: 1 0 444848 122576 5824 37344 288 0 288 0 773 1914 48 5 47 0 0
108master stdout: 0 0 444012 121320 5824 37348 1212 0 1212 0 823 1917 47 6 45 1 0
109master stdout: 0 0 443984 121204 5824 37372 0 0 0 0 797 1796 52 5 43 0 0
110master stdout: 0 0 438800 117244 5824 37360 3896 0 3896 0 910 2123 49 6 45 0 0
111master stdout: 1 0 438768 117136 5840 37368 0 0 0 136 811 1926 48 6 45 0 0
112^CAttempting to stopping cleanly, interrupt again to kill
113Sending kill to master 6dad5cb9-57f7-46e0-bad7-07ab117369a5
114```
115
116
117### mco shell start
118
119Starts a command in the background and tells you the id that has been assigned
120to it. You can then use `mco shell watch`, `mco shell kill`, `mco shell list`
121to monitor this process and observe its output
122
123```
124$ mco shell -I /master/ start vmstat 1
125
126 * [ ============================================================> ] 1 / 1
127
128master: 0dd67fac-734f-4824-8b4d-03100d4f9d07
129
130Finished processing 1 / 1 hosts in 76.37 ms
131```
132
133
134### mco shell watch
135
136Shows you the output of a command you previously started with `mco shell start`
137
138```
139$ mco shell watch 0dd67fac-734f-4824-8b4d-03100d4f9d07
140
141 * [ ============================================================> ] 2 / 2
142
143master stdout: procs -----------memory---------- ---swap-- -----io---- --system-- -----cpu-----
144master stdout: r b swpd free buff cache si so bi bo in cs us sy id wa st
145master stdout: 2 0 431448 110704 8484 40644 34 29 52 48 40 47 6 1 93 0 0
146```
147
148### mco shell list
149
150Show a list of running jobs.
151
152```
153$ mco shell list -v
154
155 * [ ============================================================> ] 2 / 2
156
157master:
158 0dd67fac-734f-4824-8b4d-03100d4f9d07
159 1fd3961a-f48d-4119-b988-146b490a5ca3
160 d174e20b-9cdb-4c14-9f34-fd29995f30cb
161 ea809b20-3123-46b4-bf59-10ff7251ca9b
162
163Finished processing 2 / 2 hosts in 142.34 ms
164```
165
166### mco shell kill
167
168Kill a running job.
169
170```
171$ mco shell kill 0dd67fac-734f-4824-8b4d-03100d4f9d07
172
173 * [ ============================================================> ] 2 / 2
174
175
176Finished processing 2 / 2 hosts in 170.17 ms
177```
178
){kind=link}