PROJECT MOVED -> https://lab.nexedi.cn/nexedi/slapos.core
[slapos.core.git] / slapos / README.console.txt
1 console
2 -------
3
4 The slapconsole tool allows to interact with a SlapOS Master throught the SLAP
5 library.
6
7 For more information about SlapOS or slapconsole usages, please go to
8 http://community.slapos.org.
9
10 The slapconsole tool is only a bare Python console with several global variables
11 defined and initialized.
12
13
14 Initialization and configuration file
15 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
16
17 Slapconsole allows to automatically connect to a Master using URL and SSL
18 certificate from given slapos.cfg.
19 Certificate has to be *USER* certificate, manually obtained from SlapOS master
20 web interface.
21
22 Slapconsole tools reads the given slapos.cfg configuration file and use the
23 following informations :
24
25  * Master URL is read from [slapos] in the "master_url" parameter.
26  * SSL Certificate is read from [slapconsole] in the "cert_file" parameter.
27  * SSL Key is read from [slapconsole] in the "key_file" parameter.
28
29 See slapos.cfg.example for examples.
30
31
32 Global functions/variables
33 ~~~~~~~~~~~~~~~~~~~~~~~~~~
34
35  * "request()" is a shorthand for slap.registerOpenOrder().request() allowing
36    to request instances.
37  * "supply()" is a shorthand for slap.registerSupply().supply() allowing to
38    request software installation.
39
40 For more information about those methods, please read the SLAP library
41 documentation.
42
43  * "product" is an instance of slap.SoftwareProductCollection whose only goal is to retrieve
44    the URL of the best Software Release of a given Software Product as attribute.
45    for each attribute call, it will retrieve from the SlapOS Master the best
46    available Software Release URL and return it.
47
48    This allows to request instances in a few words, i.e::
49
50       request("mykvm", "http://www.url.com/path/to/current/best/known/kvm/software.cfg")
51
52    can be simplified into ::
53
54      request("mykvm", product.kvm)
55
56  * "slap" is an instance of the SLAP library. It is only used for advanced usages.
57 "slap" instance is obtained by doing ::
58
59   slap = slapos.slap.slap()
60   slap.initializeConnection(config.master_url,
61     key_file=config.key_file, cert_file=config.cert_file)
62     
63
64 Examples
65 ~~~~~~~~
66
67 ::
68
69   >>> # Request instance
70   >>> request(product.kvm, "myuniquekvm")
71
72   >>> # Request instance on specific computer
73   >>> request(product.kvm, "myotheruniquekvm",
74     filter_kw={ "computer_guid": "COMP-12345" })
75   
76   >>> # Request instance, specifying parameters (here nbd_ip and nbd_port)
77   >>> request(product.kvm, "mythirduniquekvm",
78     partition_parameter_kw={"nbd_ip":"2a01:e35:2e27:460:e2cb:4eff:fed9:48dc",
79     "nbd_port":"1024"})
80
81   >>> # Request software installation on owned computer
82   >>> supply(product.kvm, "mycomputer")
83
84   >>> # Fetch existing instance status
85   >>> request(product.kvm, "myuniquekvm").getState()
86
87   >>> # Fetch instance information on already launched instance
88   >>> request(product.kvm, "myuniquekvm").getConnectionParameter("url")