platform docs: updated commands, removed config items that are no longer supported...
[leap_doc.git] / docs / platform / commands.md
1 @title = 'Command Line Reference'
2
3 The command "leap" can be used to manage a bevy of servers running the LEAP platform from the comfort of your own home.
4
5
6 # Global Options
7
8 * `--log FILE`
9 Override default log file
10 Default Value: None
11
12 * `-v|--verbose LEVEL`
13 Verbosity level 0..5
14 Default Value: 1
15
16 * `--[no-]color`
17 Disable colors in output
18
19 * `--debug`
20 Enable debugging library (leap_cli development only)
21
22 * `--help`
23 Show this message
24
25 * `--version`
26 Display version number and exit
27
28 * `--yes`
29 Skip prompts and assume "yes"
30
31
32 # leap add-user  USERNAME
33
34 Adds a new trusted sysadmin by adding public keys to the "users" directory.
35
36
37
38 **Options**
39
40 * `--pgp-pub-key arg`
41 OpenPGP public key file for this new user
42 Default Value: None
43
44 * `--ssh-pub-key arg`
45 SSH public key file for this new user
46 Default Value: None
47
48 * `--self`
49 Add yourself as a trusted sysadin by choosing among the public keys available for the current user.
50
51
52 # leap cert
53
54 Manage X.509 certificates
55
56
57
58 ## leap cert ca
59
60 Creates two Certificate Authorities (one for validating servers and one for validating clients).
61
62 See see what values are used in the generation of the certificates (like name and key size), run `leap inspect provider` and look for the "ca" property. To see the details of the created certs, run `leap inspect <file>`.
63
64 ## leap cert csr
65
66 Creates a CSR for use in buying a commercial X.509 certificate.
67
68 Unless specified, the CSR is created for the provider's primary domain. The properties used for this CSR come from `provider.ca.server_certificates`.
69
70 **Options**
71
72 * `--domain DOMAIN`
73 Specify what domain to create the CSR for.
74 Unless specified, the CSR is created for the provider's primary domain. The properties used for this CSR come from `provider.ca.server_certificates`.
75 Default Value: None
76
77
78 ## leap cert dh
79
80 Creates a Diffie-Hellman parameter file.
81
82
83
84 ## leap cert update  FILTER
85
86 Creates or renews a X.509 certificate/key pair for a single node or all nodes, but only if needed.
87
88 This command will a generate new certificate for a node if some value in the node has changed that is included in the certificate (like hostname or IP address), or if the old certificate will be expiring soon. Sometimes, you might want to force the generation of a new certificate, such as in the cases where you have changed a CA parameter for server certificates, like bit size or digest hash. In this case, use --force. If <node-filter> is empty, this command will apply to all nodes.
89
90 **Options**
91
92 * `--force`
93 Always generate new certificates
94
95
96 # leap clean
97
98 Removes all files generated with the "compile" command.
99
100
101
102 # leap compile
103
104 Compile generated files.
105
106
107
108 ## leap compile all  [ENVIRONMENT]
109
110 Compiles node configuration files into hiera files used for deployment.
111
112
113
114 ## leap compile zone
115
116 Compile a DNS zone file for your provider.
117
118
119 Default Command: all
120
121 # leap db
122
123 Database commands.
124
125
126
127 ## leap db destroy  [FILTER]
128
129 Destroy all the databases. If present, limit to FILTER nodes.
130
131
132
133 # leap deploy  FILTER
134
135 Apply recipes to a node or set of nodes.
136
137 The FILTER can be the name of a node, service, or tag.
138
139 **Options**
140
141 * `--ip IPADDRESS`
142 Override the default SSH IP address.
143 Default Value: None
144
145 * `--port PORT`
146 Override the default SSH port.
147 Default Value: None
148
149 * `--tags TAG[,TAG]`
150 Specify tags to pass through to puppet (overriding the default).
151 Default Value: leap_base,leap_service
152
153 * `--dev`
154 Development mode: don't run 'git submodule update' before deploy.
155
156 * `--fast`
157 Makes the deploy command faster by skipping some slow steps. A "fast" deploy can be used safely if you recently completed a normal deploy.
158
159 * `--force`
160 Deploy even if there is a lockfile.
161
162 * `--[no-]sync`
163 Sync files, but don't actually apply recipes.
164
165
166 # leap env
167
168 Manipulate and query environment information.
169
170 The 'environment' node property can be used to isolate sets of nodes into entirely separate environments. A node in one environment will never interact with a node from another environment. Environment pinning works by modifying your ~/.leaprc file and is dependent on the absolute file path of your provider directory (pins don't apply if you move the directory)
171
172 ## leap env ls
173
174 List the available environments. The pinned environment, if any, will be marked with '*'.
175
176
177
178 ## leap env pin  ENVIRONMENT
179
180 Pin the environment to ENVIRONMENT. All subsequent commands will only apply to nodes in this environment.
181
182
183
184 ## leap env unpin
185
186 Unpin the environment. All subsequent commands will apply to all nodes.
187
188
189 Default Command: ls
190
191 # leap facts
192
193 Gather information on nodes.
194
195
196
197 ## leap facts update  FILTER
198
199 Query servers to update facts.json.
200
201 Queries every node included in FILTER and saves the important information to facts.json
202
203 # leap help  command
204
205 Shows a list of commands or help for one command
206
207 Gets help for the application or its commands. Can also list the commands in a way helpful to creating a bash-style completion function
208
209 **Options**
210
211 * `-c`
212 List commands one per line, to assist with shell completion
213
214
215 # leap inspect  FILE
216
217 Prints details about a file. Alternately, the argument FILE can be the name of a node, service or tag.
218
219
220
221 **Options**
222
223 * `--base`
224 Inspect the FILE from the provider_base (i.e. without local inheritance).
225
226
227 # leap list  [FILTER]
228
229 List nodes and their classifications
230
231 Prints out a listing of nodes, services, or tags. If present, the FILTER can be a list of names of nodes, services, or tags. If the name is prefixed with +, this acts like an AND condition. For example:
232
233 `leap list node1 node2` matches all nodes named "node1" OR "node2"
234
235 `leap list openvpn +local` matches all nodes with service "openvpn" AND tag "local"
236
237 **Options**
238
239 * `--print arg`
240 What attributes to print (optional)
241 Default Value: None
242
243 * `--disabled`
244 Include disabled nodes in the list.
245
246
247 # leap local
248
249 Manage local virtual machines.
250
251 This command provides a convient way to manage Vagrant-based virtual machines. If FILTER argument is missing, the command runs on all local virtual machines. The Vagrantfile is automatically generated in 'test/Vagrantfile'. If you want to run vagrant commands manually, cd to 'test'.
252
253 ## leap local destroy  [FILTER]
254
255 Destroys the virtual machine(s), reclaiming the disk space
256
257
258
259 ## leap local reset  [FILTER]
260
261 Resets virtual machine(s) to the last saved snapshot
262
263
264
265 ## leap local save  [FILTER]
266
267 Saves the current state of the virtual machine as a new snapshot
268
269
270
271 ## leap local start  [FILTER]
272
273 Starts up the virtual machine(s)
274
275
276
277 ## leap local status  [FILTER]
278
279 Print the status of local virtual machine(s)
280
281
282
283 ## leap local stop  [FILTER]
284
285 Shuts down the virtual machine(s)
286
287
288
289 # leap mosh  NAME
290
291 Log in to the specified node with an interactive shell using mosh (requires node to have mosh.enabled set to true).
292
293
294
295 # leap new  DIRECTORY
296
297 Creates a new provider instance in the specified directory, creating it if necessary.
298
299
300
301 **Options**
302
303 * `--contacts arg`
304 Default email address contacts.
305 Default Value: None
306
307 * `--domain arg`
308 The primary domain of the provider.
309 Default Value: None
310
311 * `--name arg`
312 The name of the provider.
313 Default Value: None
314
315 * `--platform arg`
316 File path of the leap_platform directory.
317 Default Value: None
318
319
320 # leap node
321
322 Node management
323
324
325
326 ## leap node add  NAME [SEED]
327
328 Create a new configuration file for a node named NAME.
329
330 If specified, the optional argument SEED can be used to seed values in the node configuration file.
331
332 The format is property_name:value.
333
334 For example: `leap node add web1 ip_address:1.2.3.4 services:webapp`.
335
336 To set nested properties, property name can contain '.', like so: `leap node add web1 ssh.port:44`
337
338 Separeate multiple values for a single property with a comma, like so: `leap node add mynode services:webapp,dns`
339
340 **Options**
341
342 * `--local`
343 Make a local testing node (by automatically assigning the next available local IP address). Local nodes are run as virtual machines on your computer.
344
345
346 ## leap node init  FILTER
347
348 Bootstraps a node or nodes, setting up SSH keys and installing prerequisite packages
349
350 This command prepares a server to be used with the LEAP Platform by saving the server's SSH host key, copying the authorized_keys file, installing packages that are required for deploying, and registering important facts. Node init must be run before deploying to a server, and the server must be running and available via the network. This command only needs to be run once, but there is no harm in running it multiple times.
351
352 **Options**
353
354 * `--ip IPADDRESS`
355 Override the default SSH IP address.
356 Default Value: None
357
358 * `--port PORT`
359 Override the default SSH port.
360 Default Value: None
361
362 * `--echo`
363 If set, passwords are visible as you type them (default is hidden)
364
365
366 ## leap node mv  OLD_NAME NEW_NAME
367
368 Renames a node file, and all its related files.
369
370
371
372 ## leap node rm  NAME
373
374 Removes all the files related to the node named NAME.
375
376
377
378 # leap ssh  NAME
379
380 Log in to the specified node with an interactive shell.
381
382
383
384 **Options**
385
386 * `--port arg`
387 Override ssh port for remote host
388 Default Value: None
389
390 * `--ssh arg`
391 Pass through raw options to ssh (e.g. --ssh '-F ~/sshconfig')
392 Default Value: None
393
394
395 # leap test
396
397 Run tests.
398
399
400
401 ## leap test init
402
403 Creates files needed to run tests.
404
405
406
407 ## leap test run
408
409 Run tests.
410
411
412
413 **Options**
414
415 * `--[no-]continue`
416 Continue over errors and failures (default is --no-continue).
417
418 Default Command: run