slapos.usage.rst 11.3 KB
Newer Older
1 2 3 4 5
=========================
SlapOS command line usage
=========================


6 7
Notes
-----
Marco Mariani's avatar
Marco Mariani committed
8

9
* Default SlapOS Master is https://slap.vifib.com. It can be changed by altering configuration files or with the ``--master-url``
Marco Mariani's avatar
Marco Mariani committed
10
  argument for commands that support it.
Marco Mariani's avatar
Marco Mariani committed
11

Marco Mariani's avatar
Marco Mariani committed
12
* Most commands take a configuration file parameter, provided as ``--cfg /path/to/file.cfg``.
Marco Mariani's avatar
Marco Mariani committed
13

Marco Mariani's avatar
Marco Mariani committed
14
  If no such argument is provided:
15

Marco Mariani's avatar
Marco Mariani committed
16 17
  * "node" commands read configuration from :file:`/etc/opt/slapos/slapos.cfg`, or the file referenced by the
    ``SLAPOS_CONFIGURATION`` environment variable.
Marco Mariani's avatar
Marco Mariani committed
18

Marco Mariani's avatar
Marco Mariani committed
19
  * likewise, "client" commands (request, supply...) use :file:`~/.slapos/slapos.cfg`, or the ``SLAPOS_CLIENT_CONFIGURATION`` variable.
20 21 22



23
..
Marco Mariani's avatar
Marco Mariani committed
24
  XXX TODO software_group?, computer_group?
25 26 27



Marco Mariani's avatar
Marco Mariani committed
28 29
Common options
--------------
30

Marco Mariani's avatar
Marco Mariani committed
31
Without arguments, the ``slapos`` program lists all the available commands and common options.
Marco Mariani's avatar
Marco Mariani committed
32 33

.. program-output:: python slapos
34 35


Marco Mariani's avatar
Marco Mariani committed
36 37 38 39
The ``-q`` and ``-v`` options control the verbosity of console output (``-v``: DEBUG, default: INFO, ``-q``: WARNING).

Output to a logfile is not affected, and is the same as ``-v``.

40 41 42 43 44


SlapOS Client commands
----------------------

Marco Mariani's avatar
Marco Mariani committed
45
These commands are used by clients (as human beings or programs) to manage their own instances.
46

47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62
configure client
~~~~~~~~~~~~~~~~

configure slapos client with an existing account

.. program-output:: python slapos help configure client


configure local
~~~~~~~~~~~~~~~~

configure slapos node, slapos proxy and slapos client to work in a self-contained, autonomous way, without any external slapos master.

.. program-output:: python slapos help configure local


Marco Mariani's avatar
Marco Mariani committed
63 64
request
~~~~~~~
Marco Mariani's avatar
Marco Mariani committed
65 66 67

.. program-output:: python slapos help request

68 69
Request the deployment of a service (instance).

Marco Mariani's avatar
Marco Mariani committed
70
Examples
71

72 73 74
* Request a wordpress instance named "mybeautifulinstance" on any available machine (either owned by user, public, or shared by other user to current user)::

    $ slapos request mybeautifulinstance wordpress
Marco Mariani's avatar
Marco Mariani committed
75

76 77 78
* Request a wordpress instance named "My Beautiful Instance" on Node named "COMP-12345"::

    $ slapos request "My Beautiful Instance" wordpress --node computer_guid=COMP-12345
79

Marco Mariani's avatar
Marco Mariani committed
80
* Request a kvm instance named "mykvm" on Node named "COMP-12345", specifying nbd-host and nbd-ip parameters::
Marco Mariani's avatar
Marco Mariani committed
81

82
    $ slapos request mykvm kvm --node computer_guid=COMP-12345 --parameters \
83
        nbd-host=debian.nbd.vifib.net nbd-port=1024
84

Marco Mariani's avatar
Marco Mariani committed
85 86 87
* Request a kvm instance specifying the full URL, with default settings::

    $ slapos request mykvm \
88 89 90 91 92
        https://lab.node.vifib.com/nexedi/slapos/raw/1.0.56/software/kvm/software.cfg

* Request a kvm instance specifying an alias from SlapOS Master, with default settings::

    $ slapos request mykvm product.kvm
Marco Mariani's avatar
Marco Mariani committed
93

94 95
..
  XXX update me
Marco Mariani's avatar
Marco Mariani committed
96 97 98
In these examples, ``wordpress`` and ``kvm`` are aliases for the full URL, and are defined in :file:`slapos-client.cfg`.


99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117
info
~~~~

.. program-output:: python slapos help info

Get informations of specified instance, like connection parameters, Software Release.
Return an error if instance does not exist for the current user.

Examples:

* Ask informations about an instance named "My Service"

    $ slapos info "My Service"


list
~~~~

.. program-output:: python slapos help list
118

119
List all deployed services owned by current user.
120
From SlapOS Master point of view, it should return the list of all non-destroyed Instance Trees.
121

Marco Mariani's avatar
Marco Mariani committed
122 123 124 125 126 127
..
  search
  ~~~~~~
  Note: Not yet implemented.
  Usage:
    slapos search <search parameters ex. computer region, instance reference, source_section, etc.>
128

Marco Mariani's avatar
Marco Mariani committed
129
  Returns visible instances matching search parameters.
130 131


Marco Mariani's avatar
Marco Mariani committed
132 133
supply
~~~~~~
Marco Mariani's avatar
Marco Mariani committed
134 135

.. program-output:: python slapos help supply
136

Marco Mariani's avatar
Marco Mariani committed
137 138
Ask installation of a software on a specific node or group of nodes.
Nodes will then be ready to accept instances of specified software.
139

Marco Mariani's avatar
Marco Mariani committed
140
Examples
Marco Mariani's avatar
Marco Mariani committed
141

142 143 144 145 146 147 148
* Ask installation of kvm Software Release on COMP-12345::

    $ slapos supply kvm COMP-12345

* Ask installation of kvm Software Relase on COMP-12345, using alias from SlapOS Master::

    $ slapos supply product.kvm COMP-12345
Marco Mariani's avatar
Marco Mariani committed
149 150


151
In this example, ``kvm`` is an alias for the full URL, and is defined in :file:`slapos-client.cfg`.
152

Marco Mariani's avatar
Marco Mariani committed
153 154
remove
~~~~~~
Marco Mariani's avatar
Marco Mariani committed
155 156

.. program-output:: python slapos help remove
157

Marco Mariani's avatar
Marco Mariani committed
158
Ask removal of a software from a specific node or group of nodes. Existing instances won't work anymore.
Marco Mariani's avatar
Marco Mariani committed
159

160 161
..
  XXX "slapos autounsupply a.k.a slapos cleanup"
162

Marco Mariani's avatar
Marco Mariani committed
163
Examples
Marco Mariani's avatar
Marco Mariani committed
164

165
* Ask removal of kvm Software Release on COMP-12345::
Marco Mariani's avatar
Marco Mariani committed
166

167
    $ slapos remove kvm COMP-12345
Marco Mariani's avatar
Marco Mariani committed
168

169
In this example, ``kvm`` is an alias for the full URL, and is defined in :file:`slapos-client.cfg`.
170

Marco Mariani's avatar
Marco Mariani committed
171 172 173 174 175 176
..
  autosupply
  ~~~~~~~~~~
  Note: Not yet implemented.
  Usage:
    slapos autosupply <software | software_group> <computer_guid | computer_group>
177

Marco Mariani's avatar
Marco Mariani committed
178 179
  Like "slapos suppply", but on-demand. Software will be (re)installed only when at least one instance
  of this software is requested. When no instance of this software is deployed on the node, it will be uninstalled.
180 181


Marco Mariani's avatar
Marco Mariani committed
182 183
console
~~~~~~~
Marco Mariani's avatar
Marco Mariani committed
184 185 186

.. program-output:: python slapos help console

187 188


Marco Mariani's avatar
Marco Mariani committed
189 190 191 192 193 194
..
  <stop|start|destroy>
  ~~~~~~~~~~~~~~~~~~~~
  Note: Not yet implemented.
  Usage:
    slapos <stop|start|destroy> <instance reference>
195

Marco Mariani's avatar
Marco Mariani committed
196
  Ask start/stop/destruction of selected instance.
197

Marco Mariani's avatar
Marco Mariani committed
198
  Example:
199

Marco Mariani's avatar
Marco Mariani committed
200
    * Ask to stop "mywordpressinstance"::
201

Marco Mariani's avatar
Marco Mariani committed
202
        $ slapos stop mywordpressinstance
203 204 205 206 207 208



SlapOS Node commands
--------------------

Marco Mariani's avatar
Marco Mariani committed
209
This group of commands is used to control the current SlapOS Node. They are only useful to Node administrators.
210

Marco Mariani's avatar
Marco Mariani committed
211 212
node, node status
~~~~~~~~~~~~~~~~~
213

214
These are both aliases for ``node supervisorctl status``.
Marco Mariani's avatar
Marco Mariani committed
215 216
It displays the status of the node, also running the supervisor daemon if needed.

Marco Mariani's avatar
Marco Mariani committed
217
.. program-output:: python slapos help node supervisorctl status
Marco Mariani's avatar
Marco Mariani committed
218

219

Marco Mariani's avatar
Marco Mariani committed
220 221
node register
~~~~~~~~~~~~~
222

Marco Mariani's avatar
Marco Mariani committed
223 224
.. program-output:: python slapos help node register

225

226 227 228 229
This will register the current node, and generate the SlapOS configuration file.

The command requires an authentication token, either provided as an argument,
or given at the interactive prompt.
230
Go to the SlapOS Master web page, click ``Servers`` and them ``Token``.
Marco Mariani's avatar
Marco Mariani committed
231
A token is valid for a single ``node register`` command and will expire after one day.
232

233 234
..
  XXX-Cedric should be like this: If desired node name is already taken, will raise an error.
Marco Mariani's avatar
Marco Mariani committed
235 236
  XXX-Cedric: --master-url-web url will disappear in REST API. Currently, "register" uses
              SlapOS master web URL to register computer, so it needs the web URL (like http://www.slapos.org)
237

238 239
If the Node is already registered (:file:`slapos.cfg` and certificate are already present), the command
issues a warning, backups the original configuration and creates a new one.
240

241 242
..
  XXX-Cedric should check for IPv6 in selected interface
243

Marco Mariani's avatar
Marco Mariani committed
244

245 246 247
Notes:
******

Marco Mariani's avatar
Marco Mariani committed
248
* "IPv6 interface" and "create tap" won't be put at all in the SlapOS Node configuration file if not explicitly written.
Marco Mariani's avatar
Marco Mariani committed
249

Marco Mariani's avatar
Marco Mariani committed
250
Examples
251

252
* Register computer named "mycomputer" to SlapOS Master::
253

Marco Mariani's avatar
Marco Mariani committed
254
    $ slapos node register mycomputer
255

Marco Mariani's avatar
Marco Mariani committed
256 257
* Register computer named "mycomputer" to SlapOS Master using br0 as primary interface,
  tap0 as IPv6 interface and different local ipv4 subnet::
258

Marco Mariani's avatar
Marco Mariani committed
259 260
    $ slapos node register mycomputer --interface-name br0 --ipv6-interface tap0 \
        --ipv4-local-network 11.0.0.0/16
261

Marco Mariani's avatar
Marco Mariani committed
262 263 264
* Register computer named "mycomputer" to another SlapOS master accessible via https://www.myownslaposmaster.com,
  and SLAP webservice accessible via https://slap.myownslaposmaster.com (note that this address should be the
  "slap" webservice URL, not web URL)::
Marco Mariani's avatar
Marco Mariani committed
265 266 267

    $ slapos node register mycomputer --master-url https://slap.myownslaposmaster.com \
        --master-url-web https://www.myownslaposmaster.com
268

269
* Register computer named "mycomputer" to SlapOS Master, and ask to create tap interface to be able to host KVMs::
270

Marco Mariani's avatar
Marco Mariani committed
271
    $ slapos node register mycomputer --create-tap
272

Marco Mariani's avatar
Marco Mariani committed
273

Marco Mariani's avatar
Marco Mariani committed
274 275
node software
~~~~~~~~~~~~~
276

Marco Mariani's avatar
Marco Mariani committed
277
.. program-output:: python slapos help node software
278

279 280 281

Return values:
**************
Marco Mariani's avatar
Marco Mariani committed
282

283
(among other standard Python return values)
284

Marco Mariani's avatar
Marco Mariani committed
285 286
* 0    Everything went fine.
* 1    At least one software was not correctly installed.
287

288

Marco Mariani's avatar
Marco Mariani committed
289 290
node instance
~~~~~~~~~~~~~
291

Marco Mariani's avatar
Marco Mariani committed
292
.. program-output:: python slapos help node instance
293

294 295 296

Return values:
**************
Marco Mariani's avatar
Marco Mariani committed
297

298
(among other standard Python return values)
299

Marco Mariani's avatar
Marco Mariani committed
300
* 0    Everything went fine.
301
* 1    At least one instance was not correctly processed.
Marco Mariani's avatar
Marco Mariani committed
302
* 2    At least one promise has failed.
303

Marco Mariani's avatar
Marco Mariani committed
304

305 306 307 308 309 310 311 312 313 314 315 316 317
node collect
~~~~~~~~~~~~~

.. program-output:: python slapos help node collect


Return values:
**************

* 0    Everything went fine.
* 1    Fail to collect computer information.


Marco Mariani's avatar
Marco Mariani committed
318 319
node report
~~~~~~~~~~~
320

Marco Mariani's avatar
Marco Mariani committed
321
.. program-output:: python slapos help node report
322

323

324 325 326

Return values:
**************
Marco Mariani's avatar
Marco Mariani committed
327

328
(among other standard Python return values)
329

Marco Mariani's avatar
Marco Mariani committed
330 331
* 0    Everything went fine.
* 1    At least one instance hasn't correctly been processed.
332 333


Marco Mariani's avatar
Marco Mariani committed
334 335 336 337
node start|stop|restart|tail|status
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

::
338

Marco Mariani's avatar
Marco Mariani committed
339
 usage: slapos node <start|stop|restart|tail|status> [-h] [--cfg CFG] <instance>:[process]
340

Marco Mariani's avatar
Marco Mariani committed
341
 Start/Stop/Restart/Show stdout/stderr of instance and/or process.
342

Marco Mariani's avatar
Marco Mariani committed
343
 optional arguments:
344 345 346 347
  -h, --help       show this help message and exit
  --cfg CFG        SlapOS configuration file (default: $SLAPOS_CONFIGURATION
                   or /etc/opt/slapos/slapos.cfg)

348

Marco Mariani's avatar
Marco Mariani committed
349
Examples
350

Marco Mariani's avatar
Marco Mariani committed
351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366
* Start all processes of slappart3::

    $ slapos node start slappart3:

* Stop only apache in slappart1::

    $ slapos node stop slappart1:apache

* Show stdout/stderr of mysqld in slappart2::

    $ slapos node tail slappart2:mysqld



node supervisorctl
~~~~~~~~~~~~~~~~~~
Marco Mariani's avatar
Marco Mariani committed
367 368

.. program-output:: python slapos help node supervisorctl
369 370


Marco Mariani's avatar
Marco Mariani committed
371 372
node supervisord
~~~~~~~~~~~~~~~~
Marco Mariani's avatar
Marco Mariani committed
373 374

.. program-output:: python slapos help node supervisord
375

376 377


Marco Mariani's avatar
Marco Mariani committed
378 379 380 381 382 383
..
  node log
  ~~~~~~~~
  Note: Not yet implemented.
  Usage:
    slapos node log <software|instance|report>
384

Marco Mariani's avatar
Marco Mariani committed
385 386 387 388 389 390 391 392 393
  Display log.





SlapOS Miscellaneous commands
-----------------------------

394 395 396 397 398 399 400 401 402 403 404 405
configure client
~~~~~~~~~~~~~~~~

.. program-output:: python slapos help configure client


This creates a client configuration file, and downloads a certificate + key pair
from the SlapOS Master. They will be used for all the "slapos client" commands.

The command requires an authentication token, either provided as an argument,
or given at the interactive prompt.

406
Go to the SlapOS Master web page, click ``Account``, then ``Token``.
Marco Mariani's avatar
Marco Mariani committed
407
A token is valid for a single ``configure client`` command and will expire after one day.
408 409


410 411
cachelookup binary-sr
~~~~~~~~~~~~~~~~~~~~~
Marco Mariani's avatar
Marco Mariani committed
412

413
.. program-output:: python slapos help cachelookup binary-sr
Marco Mariani's avatar
Marco Mariani committed
414 415 416 417


Examples

418 419 420 421 422 423 424 425 426 427 428 429 430 431 432
* See if the KVM Software Release is available in precompiled format for our distribution::

    $ slapos cachelookup binary-sr https://lab.nexedi.com/nexedi/slapos/raw/1.0.232/software/kvm/software.cfg
    Software URL: https://lab.nexedi.com/nexedi/slapos/raw/1.0.232/software/kvm/software.cfg
    MD5:          248e006f4d007ca7060b16c9b0cb6bc8
    --------------------------------------------------------------------
        multiarch     distribution version   id   compatible? verified? 
    --------------------------------------------------------------------
     x86_64-linux-gnu    Ubuntu     18.04  bionic      no        yes    
     x86_64-linux-gnu    Ubuntu     20.04  focal       no        yes    
     x86_64-linux-gnu    debian      10.9              no        yes    
     x86_64-linux-gnu    debian      11.2             yes        yes    
     x86_64-linux-gnu    debian      8.11              no        yes    
     x86_64-linux-gnu    debian      9.13              no        yes    
    --------------------------------------------------------------------
Marco Mariani's avatar
Marco Mariani committed
433

Marco Mariani's avatar
Marco Mariani committed
434
You can also use the corresponding hash value in place of the URL.
Marco Mariani's avatar
Marco Mariani committed
435 436 437